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About This Book 





Purpose 


This book explains how to use SilverStream eXtend Workbench tools and facilities. 


Audience 


Use this guide if you are developing, assembling, or deploying J2EE and Web Service 


applications using Workbench. 


Prerequisites 


This book assumes that you are familiar with the Java programming language, the Internet, and 
Web applications. You can find learning materials on these topics readily available from a 
variety of public and commercial sources. 


Organization 


Here’s a summary of what you’ll find in this book: 





Topic 


Explains how to 





Workbench Basics 


Perform basic operations such as opening files, setting 
preferences, creating Workbench profiles, and using version 
control 





Projects and Archives 


Work with projects to create and maintain J2EE components 
and archives 





Archive Deployment 


Deploy J2EE archives using Workbench 





Component Wizards 


Use Workbench wizards to create EJBs, JSP pages, servlets, 
Java classes, JavaBeans, and tag handler classes (all wizards 
have built-in J2EE logic that facilitates the creation and 
deployment of well-structured J2EE components) 





Web Service Wizard 








Use the Web Service Wizard to generate the Java classes you 
need to create and access Web Services 











About This Book 








Topic 


Explains how to 





Source Editors 


Use the core functionality of Workbench source editors 














XML Editors Use the XML facilities provided by Workbench to create and 
edit XML files 

WSDL Editor Use the WSDL Editor to create and edit WSDL documents 

Registry Manager Use the Registry Manager to browse and publish to Web 


Service registries 





Deployment Descriptor 


Construct and populate J2EE-compatible deployment 














Editor descriptors that are used to assemble and deploy applications 

Deployment Plan Editor Create a deployment plan that performs all the tasks 
associated with deploying J2EE modules and applications to a 
SilverStream server 

Debugger Find runtime errors in Java applications (server-side objects 


such as J2EE applications as well as client-side objects) by 
controlling and monitoring the execution of Java code 














Workbench Basics 





SilverStream eXtend Workbench is an extensible IDE for developing and deploying J2EE 
and Web Service applications. Workbench automates and simplifies many tasks associated 
with J2EE and Web Service development, including creating and maintaining J2EE archives, 
populating and editing XML deployment descriptors, and deploying archives to a J2EE server. 


This chapter introduces the Workbench tools and facilities. It describes how to perform basic 
operations such as opening files, setting preferences, setting profiles, and using version control. 
It includes the following sections: 

e What Workbench provides 

e Workbench panes 

e Basic Workbench operations 

e Workbench wizards 

e Standard Workbench editors 

e Workbench viewers 

e Web Service tools 

e Setting preferences 

e Setting Workbench profiles 

e Using version control 

e Maintaining Todo lists 

e Specifying a debugger 

e Using Ant 

e Internationalization support 

e Extending the Workbench toolset and services 

LL) For more information about performing project-level operations, such as creating a 


project, adding files to a project, building a project, and creating an archive, see Chapter 2, 
“Projects and Archives”. 
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What Workbench provides 


Workbench is a file-system based development environment that provides: 


e Component wizards to help you create J2EE components such as JSP pages, EJBs, 
servlets, Java classes, JavaBeans, and tag libraries 


e Web Service facilities including a wizard for creating Java-based Web Service 
components, a SOAP runtime environment, and a Registry Manager for searching and 
publishing to Web Service registries 


e Graphical and text-based editors for working on Java files, JSP files, XML files, WSDL 
documents, deployment descriptors, and plain text files 


e Project views that show the structure of a project’s source files and the structure of a 
project’s generated archives 


e Project tools for building projects, creating and validating J2EE archives, and deploying 
archives to J2EE application servers 


e Version control integration that provides access from Workbench to your version control 
system 


Server independence Workbench is server-independent. When working on projects, you 
can create source files, build your project, and create archives all within Workbench, without 
any application server support. You do not need to run an application server until you are ready 
to deploy your project archives. 


You can deploy archives built in Workbench to any J2EE-compatible application server. 
Workbench provides automated deployment to leading application servers, including 
SilverStream eXtend Application Server, BEA WebLogic, IBM WebSphere, Jakarta Tomcat, 
and Oracle9i. See the Release Notes for information about supported versions. 
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Workbench panes 


Workbench consists of three resizable panes: Navigation, Output, and Edit. This section 
describes how to use these panes when creating projects. 


Archive layout, 
Archive contents, Navigation Edit Output 
or Source layout Pane Pane Pane 
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Column: 1 


The Navigation Pane The Navigation Pane lets you access various aspects of projects and 
registries. For example, the Project tab lets you view and select files from the source and archive 
directory structures. 


At the base of the Navigation Pane are three tabs: Directory, Project, and Registries. When 
either the Project or Directory tab is selected, the Navigation Pane consists of two subpanes: the 
top one shows the directories and the bottom one lists the files in any directory that you select. 
e The Directory tab lets you access files from the file system 


e The Project tab shows the directory structure of source and archive layouts 





Workbench panes 3 
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e The Registries tab lets you browse and publish to Web Service registries 


Here’s how it works: 











projects, files, and 
directories in the 
Navigation Pane 


To do this Use this Details 

Open files Double-click After you select a directory in the upper 
subpane, the lower subpane lists the files in 
the Directory and Project tabs 

Manipulate Right-click For example, depending on what you have 


selected, you can open files, compile files, 
add files to a project, remove files from a 
project, and so on 





Switch between 
open files 


Tabs in Edit Pane 


Click the tab for the file you want to make 
active 





Navigate to the 
next and previous 
open document 


Documents menu 


Use the Documents menu to navigate 
between the Next (Ctrl+F6) and Previous 
(Ctrl+Shift+F6) open document 





Switch between 
source and archive 
views 








Project tab 





You can compare how directories and files 
are structured in the sources and in the 
generated archive 


LL) For details, see “Viewing projects” on 
page 74. 








TIP You can see a file’s complete name and path by positioning the mouse pointer over it in 
the lower subpane of the Directory or Project tab. Workbench tool tips are particularly 
useful in the Archive Layout or Archive Contents view of the Project tab for comparing 
a file as it conceptually exists in the archive (such as WEB-INF/web.xml) to its file 
system name (such as C:\dev\proj4\web.xml). 


Edit Pane The Edit Pane is the file editor work area. It displays the contents of any file you 
have opened. You can use View menu items to hide the Output and Navigation Panes to give you 


additional work area. 


Output Pane The Output Pane contains tabs that display information from any of the 
following processes: build, validate, deploy, find, and version control. 


Status bar The status bar displays messages, such as when a file is saved. 
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About dialog Use the About dialog (Help>About Workbench) to check version 
information for Workbench and its components (editors, wizards, viewers, and so on). This 
dialog shows you what is installed in the product version you are running and which 
components have been individually revised. 


Basic Workbench operations 
This section tells you about: 
e Starting and stopping Workbench 
e Using proxy servers 


e Opening, saving, and closing projects and files 


Starting and stopping Workbench 


Start Workbench using the appropriate command on your operating system, such as the 
Windows Start menu (Programs>SilverStream eXtend> Workbench). 


Select File>Exit to exit Workbench. 


Using proxy servers 


If you are using a proxy server, you need to specify the proxy host and its port in xwb.conf, 
which is in the Workbench bin directory. Uncomment the following lines and specify your site’s 
values. 


vmarg -DsocksProxyHost=proxy-host 

vmarg -DsocksProxyPort=proxy-port -number 

vmarg -Dhttp.proxyHost=proxy-host 

vmarg -Dhttp.proxyPort=proxy-port -number 
If there are hosts that don’t require a proxy, you can specify them (separated by |) with this 
property: 


vmarg -Dhttp.nonProxyHosts=host1/host2... 
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Opening, saving, and closing projects and files 
This section describes how to work with project files and source files in Workbench: 
e Working with project files 
e Working with source files 


e Performing file system operations 


LL) For details about working with projects, see Chapter 2, “Projects and Archives”. 


Working with project files 


To work on an existing project, open its project file. Workbench project files have the extension 
SPF (for SilverStream project file). 


> To open a project file: 


1. Choose File>Open Project. A file selection dialog appears. 
2. Navigate to the project’s SPF file. 


3. Select the SPF file and click open (or double-click the SPF file). Workbench displays the 
project in the Project tab of the Navigation Pane. 


You cannot have multiple projects open (though you can work with multiple subprojects 
of an open project). If you have a project open and then open another unrelated project, 
Workbench closes the original project and any associated files before opening the second 
project. 


Alternatively, you can: 


1. Navigate to the project file in the Directory tab in the Navigation Pane of Workbench. 
2. Either double-click the file or right-click it and then choose Open File in the popup menu 
that appears. 


If you have opened the project file recently, you can also select it from the list under 
File>Recent Files. 


> To save a project file: 


No action is needed on your part to save a project. Whenever you modify the project contents 
or settings (for example, by adding a directory to the project), the project file is saved 
automatically. 


The project file must be writable before you can make changes to the project in Workbench. 
Typically, this means that you must check out the project file from your version control system. 
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> To close a project file: 
e Choose File>Close Project. 


Working with source files 


This section describes how to open, save, and close source files, such as Java, JSP, XML, and 
plain text files. 


> To open a source file: 
1. Choose File>Open. 


A file selection dialog appears. 
2. Navigate to the source file. 


3. Select the file and click Open (or double-click the file). Workbench displays the file in the 
appropriate source file editor (Java, JSP, XML, or Text) in the Edit Pane. 


Alternatively, you can: 


1. Navigate to the file in the Directory tab in the Navigation Pane. If you have a project open 
and the file is included in that project, you can find it in the Project tab as well. 


2. Either double-click the file or right-click it and choose Open in the popup menu that 
appears. 


If you have opened the file recently, you can also select it from the list under File>Recent Files. 
Working with open files One file is active at a time. By default, there is a tab for each open 


file in the Edit Pane. Simply click a tab to make that file active. (You can customize and turn off 
the display of tabs. See “Display preferences” on page 15.) 


You can also make an open file the active file by selecting Documents>More Documents and 
selecting the file from the list of open documents 

> To save a source file: 
e Choose File>Save. 


File>Save As enables you to save the contents of the currently open file to another file. 


TIP You can also save a file by right-clicking its tab in the Edit Pane. 





Basic Workbench operations 7 


1 


Workbench Basics 





> To close a source file: 


To close the currently selected source file, select File> Close or click the Close button in 
the upper-right corner of the source editor. 


TIP You can also close a file by right-clicking its tab in the Edit Pane. 
To close all open source files, select File>Close All. 


If you have made changes to a source file, Workbench prompts you to save that file before 
closing it, closing its parent project, or exiting Workbench. 


Performing file system operations 


You can delete and rename files from within Workbench. 


> To delete one or more files: 


1. 


Go to either the Project or Directory tab in the Navigation Pane and select the directory 
containing the files to be deleted. 


Select the files you want to delete. You can select multiple files using Shift+Click and 
Control+Click. 


Right-click and select Delete. 
Confirm the deletion. 
The files are deleted from the file system. 


If the files had been individually added to the current project (as opposed to being in the 
project because they are in a directory included in the project), you are asked whether you 
want to delete the entries from the project. 


Click Yes to have the deleted files removed from the project. 


> To rename a file: 


1. 


Go to either the Project or Directory tab in the Navigation Pane and select the directory 
containing the file. 


Select the file you want to rename. 
Right-click and select Rename. 
Specify the new name. 

The file is renamed in the file system. 


NOTE Ifyou had multiple files selected, only the first one is renamed. 
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If the file had been individually added to the current project (as opposed to being in the 
project because it is in a directory included in the project), you are asked whether you 
want the project to use the new file name. 


5. Click Yes to have the project use the new file name. 


Workbench wizards 


To speed project development, you can use Workbench wizards when creating J2EE projects or 
components. Workbench has several types of wizards: 





Wizard type 


Description 





Project wizards 








Create Workbench projects associated with J2EE archives, including: 
e Enterprise archives (EAR) 

e Web archives (WAR) 

e EJB archives (JAR) 

e Application client archives (JAR) 

e Resource adapter archives (RAR) 

e Simple Java archives (JAR) 

e Deploy-only (nonbuildable) archives 


LI For more information, see “Creating projects and subprojects” 
on page 56. 








Workbench wizards 
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Wizard type Description 
Component Create J2EE components, including: 
wizards 


e Enterprise JavaBeans 
e Servlets 

e JavaServer Pages 

e Java classes 

e JavaBeans 

e Tag handlers 


LL) For more information, see “Creating source files” on page 65 
and Chapter 4, “Component Wizards”. 





Web Service 


Generate the Java classes you need to create and access Web 














Wizard Services. 
(J For more information, see Chapter 5, “Web Service Wizard”. 
WSDL Wizard Create Web Services Description Language (WSDL) documents. 
(J For more information, see Chapter 8, “WSDL Editor”. 
Deployment Create deployment descriptors and SilverStream deployment plans. 
wizards 


LL) For more information, see Chapter 10, “Deployment 
Descriptor Editor” and Chapter 11, “Deployment Plan Editor”. 





Standard Workbench editors 


As you create J2EE applications and components, Workbench source editors and the Debugger 


help you create well-structured archives that are easy to build, deploy, debug, and maintain. 


About the Workbench source editors 


When you open a source file, the appropriate editor starts automatically. 


NOTE Opening an EAR, JAR, WAR, or ZIP file in Workbench lists the contents of the 
archive, along with some information about each entry. The listing is read-only. 
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LL) Fora summary of the core functionality provided in all the source editors, see Chapter 6, 
“Source Editors”. 


In addition, Workbench provides specialized functionality in the following editors. 


Deployment Descriptor Editor 


The Deployment Descriptor Editor lets you construct and populate J2EE deployment 
descriptors. A deployment descriptor is an XML document that provides information required 
for J2EE application assembly. 


NOTE To open an existing deployment descriptor, right-click the project or archive (in the 
Project tab) and select Open Deployment Descriptor. 


LI For more information, see Chapter 10, “Deployment Descriptor Editor”. 


Deployment Plan Editor 


The Deployment Plan Editor lets you construct and populate deployment plans for deploying 
J2EE modules and applications to a SilverStream eXtend Application Server. A deployment 
plan is an XML document that describes how a J2EE module should run in the application 
server environment. 


NOTE To open an existing deployment plan, right-click the project or archive (in the Project 
tab) and select Open Deployment Plan. 


LI For more information, see Chapter 11, “Deployment Plan Editor”. 


XML Editor 


The XML Editor lets you create, edit, and view XML files. It provides intelligent editing of 
XML files (by reading the XML DTD or Schema, it knows which elements and attributes are 
valid where) and a graphical tree view. 


(J For more information, see Chapter 7, “XML Editors”. 


WSDL Editor 


The WSDL Editor lets you create, edit, and view WSDL documents. WSDL (Web Services 
Description Language) is an XML vocabulary for describing Web Services. 


(J For more information, see Chapter 8, “WSDL Editor’. 
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Debugger 


As part of application development, you can use the SilverStream Debugger to debug server- 
based applications (such as J2EE applications) and client applications. You can invoke the 
Debugger from within Workbench. 


LI For more information, see Chapter 12, “Debugger”. 


Workbench viewers 


In addition to providing a set of source editors, Workbench provides the following viewers so 
you can view other files within Workbench: 


e Image Viewer 


e Class Viewer 


Image Viewer 


If you open a .gif, jpg, jpeg, or -png file, the file is opened in the Workbench’s Image Viewer. 
You can zoom the image: 

e  Left-click or press + to zoom in 

e Ctrl+left-click or press - to zoom out 


e  Shift+left-click or press = to restore the image to its actual size 


TIP Ifyou want these files to open in an external program, specify the file extensions and the 
program in your preferences. For more information, see “File type preferences” on 
page 20. 


Class Viewer 


If you open a .class file, information about the .class file is displayed in the Class Viewer 
(exception: double-clicking a .class file in the Project tab’s Archive Contents view opens the 
corresponding .java file in the Java Editor). 


The Class Viewer displays the following information: 


e Name of the file, its corresponding source file, and the version of the compiler 
e The class’s package statement 


e The class’s declaration 





12 


Workbench viewers 


eXtend Workbench Tools Guide 





List of all fields, sorted by visibility 
List of all methods, sorted by visibility 


The same information for all inner classes 


Web Service tools 
Workbench supports Web Service development by providing: 


(AA) 


A Web Service Wizard to help you create Java-based Web Services and Web Service 


consumers from Java classes or WSDL files 


A WSDL Editor for creating, editing, or viewing WSDL files 
A Registry Manager for publishing and discovering Web Services 


For more information, see Chapter 5, “Web Service Wizard”, Chapter 8, “WSDL Editor”, 
and Chapter 9, “Registry Manager”. 


Setting preferences 


You can configure your Workbench development environment by setting: 


General preferences 

Build preferences 

Display preferences 

Text editing preferences 
Printing preferences 
Deployment preferences 
Abbreviations preferences 
File type preferences 
Backup preferences 
Version control preferences 
Editor setup preferences 
NetBeans directories preferences 


XML Editor color preferences 
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> To specify preferences: 


1. Select Edit>Preferences. 
The Preferences dialog appears. 
2. Select the tab you want. 


3. Set your preferences. See the following sections for information about specific 
preferences. 


4. Click OK. 


General preferences 


Specify general preferences as follows: 





Setting Description 





Number of recent files Specifies how many recently open files appear in the 
Workbench File menu. Default is 10. 








Number of recent Specifies how many recently open projects appear in the 
projects Workbench File menu. Default is 5. 
Reload open projects When starting, automatically reloads the projects that were 


open when you last exited Workbench. Default is No. 





Reload open files When starting, automatically reloads the files that were open 
when you last exited Workbench. Default is No. 








Web browser Specifies the browser to use when running the Workbench help 
system. Choose a browser by typing the path or clicking the 
button. 

Enable Todo Specifies whether the Todo feature is enabled.When selected, 


Workbench displays a Todo tab in the Output Pane where you 
can maintain a Todo list of tasks. 


LL) For more information, see “Maintaining Todo lists” on 
page 37. 
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Setting 


Description 





Debugger command 








If empty, Workbench launches the SilverStream Debugger 
when you select Edit>Launch Debugger. See Chapter 12, 
“Debugger”. 


If not empty, specifies the command that Workbench invokes 
when you launch a debugger. See “Specifying a debugger” on 
page 43. 








Build preferences 


Specify build preferences as follows: 





Setting 


Description 





Always save modified 
files before compiling 


When set (the default), automatically saves all modified files 
before compiling, building, or rebuilding. When this property is 
not set, Workbench prompts for unsaved files. 


C] For more save option preferences, see “Backup 
preferences” on page 21. 





Compiler 


Specifies the compiler. Default is Javac 1.3. 





Compiler options 








Specifies the command-line options to be sent to the Java 
compiler. 








Display preferences 


Specify display preferences as follows: 





Setting 


Description 





Directory tab 








Specifies how directories and files appear in the Directory tab. 
Compact mode shows only the selected directory path and its 
related source files. Traditional mode (the default) shows all 
directories. 
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Setting 


Description 





Project tab 


Specifies how directories and files appear in the Project tab. 
Compact mode shows only the selected directory path and its 
related source files for the project. Traditional mode (the 
default) shows all directories. 





Icons in the Navigation 
Pane 


Specifies whether you want to show large or small icons, with 
or without text, in the Navigation Pane. 





Edit Pane 








Specifies the following: 
e Whether the Edit Pane displays tabs for each open file 
e Where the tabs are displayed relative to the editor 


e Whether, in stacked tabs, the tab for the open file is always in 
front. If you select this option, the row of tabs containing the 
active file moves if necessary to be in front (at the bottom 
when the tabs are above the editor and at the top if the tabs 
are below the editor) 





Text editing preferences 


Specify editor preferences as follows: 





Setting 


Description 





Font size 


Sets the screen font size in the Edit Pane. Default is 12. You can 
also set a print font size from the Print tab; see “Printing 
preferences” on page 17. 





Spaces per tab 
character 


Sets the number of spaces entered for each tab. Default is 4. 





Show line numbers 


Sets whether to hide (the default) or show line numbers in the 
Edit Pane. You can also use Ctrl+L in a source editor to toggle 
between hiding and showing line numbers for individual files. 





Show vertical margin 








Displays the margin wrap guide (set at 80 characters) at the 
right of the pane. Default is on. 
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Setting 


Description 





Highlight matching 
parentheses and braces 


As you type, highlights text within a matching set of 
parentheses and braces. Default is on. 





Use smart indenting 


When you create a new line, sets the indentation level of the 
new line based on that of the current line. Default is on. (Not 
supported in the NetBeans-based JSP and HTML editors.) 





Use spaces instead of 
tab characters 


Uses spaces when the tab key is pressed. Default is off. 





Use chromacoding 


Color-codes the text. When deselected, all text is black. Default 
is on. 





Show horizontal 
scrollbar always/only 
as needed 








Default is only as needed. 








LL) For additional text options, see Chapter 6, “Source Editors”. 


Printing preferences 


Specify printing preferences as follows: 





Setting 


Description 





Printing mode 


Sets mode to monochrome (the default) or color. For color 
printers, use color mode. 





Font size 


Sets print font size (default is 10). You can also set a screen font 
size in the Text Editing tab; see “Text editing preferences” on 
page 16. 





Print line numbers 








Sets whether or not to print line numbers. Default is to not print 
numbers. 
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Deployment preferences 


Deployment preferences are used by the Deployment Descriptor Editor and the Deployment 
Plan Editor. When you open either of these editors, Workbench loads all of the project’s classes 
(including subproject classes). The editor then uses information from the classes to populate the 
dialogs that display lists of classes, methods, member variables, and so on. If the classes are not 
up to date, the information the editors display can be incorrect or missing. 


You can control whether Workbench automatically builds a project when you access the 
Deployment Descriptor Editor or Deployment Plan Editor. You can specify one of the following 
build settings: 








Setting Description 
Always automatically Builds the project automatically when the Deployment 
build my project Descriptor Editor or Deployment Plan Editor is opened. 


This setting ensures that the editors always have access to all of 
the latest classes. 





Never automatically None of the project’s files are built when the Deployment 
build my project Descriptor Editor or Deployment Plan Editor is opened. You 
must build the projects and subprojects manually. 


Use this setting when you don’t need anything to be built (such 
as when you are editing in XML mode). In this case you can 
edit the XML files, but the list of project classes in the editor 
may be blank or out of date. 





Prompt me to build my | Prompts you to build the project each time you open one of the 
project deployment editors. 


Use this setting when you want to specify when a project build 
should occur. 














NOTE You do not need to create the archives in order for the deployment editors to load class 
information, because the editors load the classes directly from the file system, not from 
the archives. 
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You can also specify the following deployment preference: 





Setting Description 





Default server versions | Specifies the server version initially selected when you create a 
new SilverStream deployment plan. You can specify a server 
version for J2EE 1.2 projects and a server version for J2EE 1.3 
projects. 


LL) For more information, see Chapter 11, “Deployment Plan 
Editor”. 














Abbreviations preferences 


You can define abbreviations that can be expanded to one or more lines of text—such as a word 
that expands to a predefined language construct. Once you have defined an abbreviation, you 
can type its name in an editor and select Edit>Text Tools>Complete Abbreviation (or press 
Ctrl+U) to replace the abbreviation with the expanded text. 


Use %c in an abbreviation’s definition to signify where the insertion point will be positioned 
when the abbreviation has been expanded. 


For example, the abbreviation main is predefined as follows and is meant to be used in Java 
files: 


public static void main(String args[]) 


oo 
Q 


> To define an abbreviation: 


1. Select Edit>Preferences and click the Abbreviations tab. 

2. Click Add. 

3. Type the abbreviation (shortcut) in the Abbreviation text box and click OK. 
Abbreviations must be single words and are case-sensitive. 


4. Click inside the Definition text box and type the text you want the abbreviation to expand 
to. 


5. Click OK. 
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> To delete an abbreviation: 


1. Select Edit>Preferences and click the Abbreviations tab. 
2. Select the abbreviation in the Abbreviations text box. 

3. Click Delete. 

4. Click OK. 


To edit an abbreviation: 


1. Select Edit>Preferences and click the Abbreviations tab. 

2. Select the abbreviation in the Abbreviations text box. 

3. Click inside the Definition text box and change the abbreviation. 
4. Click OK. 


To use an abbreviation in your source code: 


1. Type the abbreviation shortcut in the editor. 
2. Position the cursor within the shortcut text or highlight it. 


3. Click Edit>Text Tools>Complete Abbreviation or press Ctrl+U. The shortcut text is 
replaced with the expanded text defined for that abbreviation. 


NOTE If the abbreviation text is not defined, the Complete Abbreviation command is 
ignored. 


File type preferences 


Workbench lets you use third-party tools to edit specific file types. You can set preferences that 
let you launch files in an external editor rather than opening them in Workbench. Use the File 
Types tab to associate file extensions with external editors. For each file type you can choose 
whether to open the file in: 

e Workbench 

e The Windows default editor for that file type 


e The Windows program you specify 


> To define how a file type is launched: 


1. Select Edit>Preferences and click the File Types tab. 
2. Click Add. 
3. Type the file extension in the dialog and click OK. 
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4. Specify one of the following preferences for the file type: 











Windows program 


Setting Description 

Open in Workbench (The default) Opens files using the Workbench 
source editor. 

Open using the default Opens files using the Windows default editor for 


that file type (same as double-clicking a file in 
Windows Explorer—for example, using Notepad to 
open files with the .TXT extension). 





Open using this application 








Opens files with the application you specify. You 
can type the path to the application, or click Browse 
and navigate to the application. 


NOTE Because some editors launch a new program 
instance each time you open a file, this 
setting is not always recommended. 








5. Click OK. 





CAUTION Consider the following when associating an external editor with the XML file 
extension: if you use an external editor to edit SilverStream deployment plans, you 
will not be able to take advantage of the default setup that the SilverStream editor 
provides and your project will not be associated with a deployment plan. 





Backup preferences 


You can set Workbench preferences that control: 


e  Autosave files—successive copies of a modified file (each successive save replaces the 
preceding one). Autosave files are copies of any file in the Edit Pane that has been 


modified. 


e Backup files—the original file before it was modified and saved. 


By default, autosave and backup operations are not enabled. 
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You can set global backup preferences that control how all projects are backed up. However, 
because your projects may contain files with identical names, you may want to store separate 
backup and autosave files for each project. To do so, specify a subdirectory relative to the file’s 
source directory for both backup and autosave files. Files that are backed up in parallel backup 
directories won’t be overwritten. 
NOTE When you specify a relative name for a backup or autosave directory, it will be relative 
to the source file. 
Specify autosave and/or backup preferences as follows: 
Setting Description and parameters 
Auto save enabled While you make changes to a source file in Workbench, 
periodically save a copy of the file. 
Auto save to same directory | — 
as source file (default) 
Auto save directory Specifies another directory to 
contain saved files 
You can enter an absolute path 
or specify a path that is 
relative to the source directory. 
Use Browse to search for a 
directory on the file system. 
Auto save extension Specifies the extension of 
autosave files (default is SAV) 
Auto save interval (minutes) | Specifies how often you want 
Workbench to save files 
(default is every five minutes) 
22 Setting preferences 





eXtend Workbench Tools Guide 








Setting 


Description and parameters 





Backup enabled 





When you save a source file in Workbench, make a backup copy 


of the previous version of the file. 





Backup to same directory as 
source file (default) 





Backup directory 


Specifies another directory to 
contain backup files 


You can enter an absolute path 
or specify a path that is 
relative to the source directory. 


Use Browse to search for a 
directory on the file system. 








Backup extension 





Specifies the extension of 
backup files (default is .BAK) 





> To define how files are autosaved and/or backed up: 


Select Edit>Preferences and click the Backup tab. 


Choose Auto save enabled and/or Backup enabled. 


1 
2 
3. Specify autosave and/or backup file parameters as described above. 
4 


Click OK. 


Version control preferences 


See “Using version control” on page 29. 


Editor setup preferences 


These preferences specify which types of files will be edited using the Workbench NetBeans- 


based editors. 


See “Adding files types edited by NetBeans-based editors” on page 221 and “Using the 
native Java, JSP, or HTML editor” on page 225. 
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NetBeans directories preferences 


See “Creating parser database files” on page 220. 


XML Editor color preferences 


You can specify the colors used in the XML Editor’s Source View to display different types of 
information in XML documents, such as tags, arguments, values, text, errors, and white space 
(listed in the dialog as ws). 


For each type of information, you can specify a foreground and a background color. You can 
pick from a list of colors or define your own by clicking the ellipsis button. You can also specify 
whether to use a bold font. 


> To specify colors used in the XML Editor: 


1. Select Edit>Preferences and click the tab for XML Editor colors. 


2. Select the type of information whose color you want to specify, then specify a foreground 
and/or a background color and specify whether you want to use a bold font. 


Setting Workbench profiles 
You can define the following types of Workbench profiles: 


e Server profile 
e Database profile 
e Registry profile 


Server profile 


A server profile stores information about an application server, including the server’s host 
name and port. When selected at deployment time, the server profile tells Workbench what 
server to deploy to and provides the information required for deployment to that server. A server 
profile applies to a specific server. If you are deploying to multiple servers, you need to set up a 
separate profile for each. 


Your server’s configuration determines how to specify the server profile information. For 
example, if your server uses security certificates you will specify the https protocol. The server 
configuration may also affect how you specify the server name, server port number, database 
name, and so on. 
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(For information about configuring a particular application server, see the product 
documentation for that server. 


> To create a server profile: 


1. Select Edit>Profiles. 


2. On the Servers tab of the Profiles dialog, click New. 


3. Specify settings in the Create a New Server Profile dialog as follows: 





Setting 


Description 





Profile name 


Enter a name to identify the profile. 


NOTE The server profile name cannot contain the period (.) 
character. 





Server type 


Select a server type from the list. 


Server types are organized by brand and version number. The 
version number indicates the lowest version supported by a given 
server type. A server type is often valid for multiple subsequent 
versions as well. 


As a rule, you should select the server type for your brand that is 
closest to the target server’s version, without being higher. For 
example, if your target is Version 3.7.5 of the SilverStream 
eXtend Application Server, the server type to select is 
SilverStream 3.7.4 or higher. 














Deploymenttools | Specify the directory containing the executables used to deploy to 
directory the server. 

Rapid For rapid deployment only. 

ace hey ment Enter the directory where you want Workbench to write the files 
directory 


for rapid deployment. Some servers require that files be written to 
a specific directory for rapid deploys. Make sure that you specify 
the appropriate location for your server’s configuration. See 
“Setting rapid deployment directories” on page 26 for the 
directory listings. 


G For more information on rapid deployment, see 
“Workbench rapid deployment” on page 96. 
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Setting 


Description 





Server name 


Set the server name using the following formats. 


For servers running http: 


servername 
http://servername[:port] 


For servers running https: 
https://servername[:port] 


Specify the port number if the server is not listening on the default 
port. 





Database name 


For SilverStream eXtend Application Servers only. 


Enter the name of the database to deploy to. 





Target servers 








For BEA WebLogic servers only. 


Enter the names of the target servers. 








4. Click OK to close the Create a New Server Profile dialog 
5. Click OK to close the Profiles dialog. 


Setting rapid deployment directories This table shows the rapid deployment directory 
you should specify in the Server Profile dialog. 





Server 


Rapid deployment directory 





SilverStream eXtend 
Application Server 
3.7.2 


Does not require that you specify a rapid deployment directory. 





SilverStream eXtend 
Application Server 
3.7.3 or higher 


%INSTALL_DIR%\webapps 




















BEA WebLogic %INSTALL_DIR%\config\targetname\applications 
IBM WebSphere %INSTALL_DIR%\appserver\installedapps 
Jakarta Tomcat %INSTALL_DIR%\webapps 
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Server Rapid deployment directory 





Oracle9i AS %INSTALL_DIR%\j2ee\home\applications 
Optionally, you can rapid deploy WARs to: 
%INSTALL_DIR%\j2ee\home\default-web-app 











SUN RI %INSTALL_DIR%\public_html 





Using Workbench with secure servers Workbench connects to the target J2EE server 
at deployment time using the server profile. If the server profile indicates a secure server, then 
Workbench will make the SSL connection automatically. Workbench uses the set of commercial 
Certificate Authority certificates listed in agrootca.jar (located in Workbench’s lib directory). If 
the server you are trying to deploy to uses a certificate that was issued by a CA certificate that 
is not listed in agrootca.jar, Workbench will not successfully connect to the server. You can add 
the CA certificate to agroootca.jar using any tool that allows you to modify the contents of a 
JAR file (for example, Sun’s JAR utility or WinZip). 


Database profile 


You’ ll need to set up a database profile if you use any of the following Workbench components: 








Workbench 
component When use database profiles 
EJB Wizard When creating entity beans based on a database table 





Deployment Plan Editor | When mapping the persistent fields of a container-managed 
entity bean to fields in a datasource 














The database profile provides JDBC information that enables Workbench to connect to the 
datasource and retrieve table and field information. You can create multiple profiles to support 
different databases and JDBC drivers. 


> To create a database profile: 


1. Select Edit>Profiles. 
2. On the Databases tab of the Profiles dialog, click New. 
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3. Specify settings in the Create a New Database Profile dialog as follows: 











Setting Description 
Profile name Enter any name to identify the profile. 
JDBC Driver Enter the class name of the JDBC driver. You can specify 


any JDBC 2.0-compliant driver. 


To use the Sun JOBC-ODBC bridge driver (which is 
included in the JRE), specify 
sun.jdbc.odbe.JdbcOdbcDriver. If you specify a JDBC 
driver other than Sun’s bridge driver, make sure that the 
driver class can be loaded by Workbench (see “To make the 
driver class available:” below). 





JDBC URL Enter an URL that specifies the database you want—for 
example, jdbc:odbc:TestDB 


NOTE The text you enter after the first colon is driver 
specific. 





Connection Catalog (Optional) Specify which SQL catalog (subset) of the 
database to connect to—for example, PayrollDb. If your 
database driver does not support catalogs, it will ignore this 
request. 


If supported, the connection catalog lets you set up which 
database tables are retrieved. Connection catalogs are 
useful when you are connecting to a very large database or 
only want to connect to a subset of database tables (for 
example, to exclude production database access). 





Datasource Name Specify the name of the data source to associate with this 
database profile. 


You can specify either the datasource name, like 
SilverBooks, or the full JNDI specification, like 
java:pm/JDBC/SilverBooks. 














4. Click Test to check the connection to the database specified by the JOBC URL. 


This test makes a JDBC connection to the database. The test will fail when a connection is 
not available or a setting is not correctly specified. 
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5. On the test popup, enter your database user name and password and click OK to verify 
access. 


6. Click OK to close the Create a New Database Profile dialog. 
7. Click OK to close the Profiles dialog. 


> To make the driver class available: 


1. Obtain the JAR or other archive file that contains the JDBC driver. 
2. Do one of the following: 
e Put the JAR in the Workbench lib\ext directory. 


e — Edit the Workbench configuration file (bin\xwb.conf) to point to the driver archive by 
including the line addcp path/mydriver.jar. For example: 


addcp c:/sybase/SybJConnect.jar 
3. Start Workbench. 


Registry profile 


Workbench provides a facility for defining profiles for Web Service registries. These profiles 
supply the information that allows you to search registries and deploy Web Services. 


LL) For more information on registry profiles, see “Defining registry profiles” on page 282. 


Using version control 


If you use a version control system, you can set up Workbench to access it. This enables you to 
perform version control operations on the files in your projects while working in the IDE. 


e Setting up access to version control 


e Accessing version control 
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Setting up access to version control 


Before you can perform version control operations in Workbench, you need to adjust preference 
settings to enable version control and configure support for your version control system. 


> To adjust version control settings: 


1. 


Select Edit>Preferences to display the Preferences dialog, then go to the Version 
Control tab. 

Check the Enable Version Control property. 

This turns on the version control features of Workbench. 

Select one of the available Version Control Systems. 

In this property, you’re actually choosing a version control system definition that tells 
Workbench the version control commands to support. Workbench comes with definitions 
for several popular version control systems (ClearCase, CS-RCS, CVS, PVCS, Visual 
SourceSafe). If you choose one of these, you can use it as is or edit the commands it 
defines to suit your needs and system configuration. 

You also have the option of creating version control system definitions yourself. This lets 
you set up Workbench support for just about any version control system you might have. 


Working with definitions The following topics provide more detail about working with 
version control system definitions: 


Editing a version control system definition 
Creating a version control system definition 
Distributing a version control system definition 


Deleting a version control system definition 


Editing a version control system definition 


A version control system definition specifies a list of version control menu items that 
Workbench is to display. Each menu item is mapped to a command-line operation of the 
chosen version control system and also specifies details about how that operation is to be 
executed. You can edit the list to modify, create, or delete menu items. 


> To edit a definition: 


1. 


2. 


From the Version Control tab of the Preferences dialog, select a definition from the 
Version Control Systems dropdown list. 


Click the Setup button. 
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In the Setup dialog, make your changes to the list of version control menu items: 





If you want to 


Do this 





Change the behavior of a 
menu item 


Select that item from the Version Control Command 
listbox, then edit its Command properties. 





Change the name of a 
selected menu item 


Click the Edit button. The name can include letters, 


numbers, spaces, and special characters. 


You can also edit the mnemonic character to be used for 
keyboard access to the menu item (when pressed in 
combination with the Alt key). 





Create a new menu item Click the Add button, then specify the item’s name and 


mnemonic character. Your new item will be added to the 
end of the list. 





item 


Delete a selected menu 


Click the Remove button. 





items 





Switch the order of menu Select an item you want to reposition, then use the 


arrow buttons to move it up or down in the list. 











Command properties The following table describes the command-related properties you 
can specify in the Setup dialog for version control menu items: 





Property 


Description 





Command 








A command-line operation of your version control system that 
the menu item is to execute. 


You can include environment variables in the command by 
using the syntax %varname% or ${ varname}. Workbench 
substitutes the values of these variables when the command 
executes. If the value of a variable can’t be determined, an 
empty string is substituted. 


Predefined environment variables are available via the expand 
button next to the Command property. You can select a variable 
to insert it at the current cursor position. 
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Property Description 





Reload when done Tells Workbench to try reloading the target file after the 
command executes. This is useful for commands that might 
modify the file (such as check in, check out, or get). 





Wait for execution Tells Workbench to wait until the command finishes executing 
before returning control to the user. Not waiting for execution 
can be appropriate for commands such as diff or history where 
there’s no effect on the target file. 





Execute command in Tells Workbench to execute the command relative to the 
directory of source file directory of the target file. If you don’t check this property, the 
command executes in the current directory. 














Predefined environment variables The following table describes the predefined 
environment variables you can include in the command you specify for a version control menu 

















item: 

Variable Description 

%_PATH% Full path and name of the target file. For example: 
x:/com/myco/myfile.java 

%_DIR% Directory of the target file. For example: 
x:/com/myco 

%_NAME% Name of the target file (without directory). For example: 
myfile.java 

%_BNAME% Base name of the target file (without directory and 

extension). For example: 

myfile 
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Variable 


Description 





%_EXT% 


Extension of the target file. For example: 


java 





%_PROMPT prompt-text% 


Prompts the user for a value by displaying a dialog. The 
dialog includes any prompt-text you specify. 


The value of this variable is whatever the user types in the 
dialog input field. If the user clicks the dialog’s Cancel 
button, the entire command is canceled. 





%_COMMENT% 








Prompts the user for a comment. 


The comment is saved to a temporary file. The value of this 
variable is the name of that temporary file. 








Creating a version control system definition 


If Workbench doesn’t provide a definition for your version control system, you can create one 


yourself. 


> To create a definition: 


1. From the Version Control tab of the Preferences dialog, click the Add button. 


2. When prompted, type a name for your version control system definition. 


The definition name can include letters, numbers, spaces, and certain special characters. 
The name you specify is added to the Version Control Systems dropdown list. 


Workbench also creates an XML file to store your definition. The name of this file 
matches the definition name you specify (except that spaces are replaced by underscores). 
Workbench saves your definition XML file in its Resources\version_control_config 
directory (along with the definition XML files it provides). 


3. When the Setup dialog displays, specify the details of your version control system 


definition. 


See Editing a version control system definition. 


Distributing a version control system definition 


Once you edit or create a version control system definition, you might want to copy it to other 
computers where Workbench is installed. 
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> To distribute a definition: 


1. 


Find the XML file for your version control system definition in the Workbench 
Resources\version_control_config directory. 


Copy that file to the corresponding directory on each target computer. 


When Workbench is run on those computers, the Version Control Systems dropdown list 
(on the Version Control tab of the Preferences dialog) will automatically include your 
copied definition. 


Deleting a version control system definition 


If you don’t need a particular version control system definition, you can remove it. 


> To delete a definition: 


1. 


From the Version Control tab of the Preferences dialog, select a definition from the 
Version Control Systems dropdown list. 


Click the Remove button. 


Workbench prompts you to confirm, then deletes that definition from the list. The 
definition’s XML file is deleted from the Workbench Resources\version_control_config 
directory. 
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Accessing version control 


When you use Workbench with version control access enabled, the commands specified by the 
active version control system definition are available via a popup menu. You just need to right- 
click one of the following: 

e Any file name on the Project tab of the Navigation Pane 


e An open file in the Edit Pane 


Z% SilverStream (CreditCheck) - HTML Editor -iof x] 
File Edit View Search Project Documents Help 


Eea" Ee T E -ARL 
View using: [Archive layout =] 


a | & SilverStream 
C\Doc Views \klobucher_Doc_view'DocAdmin'DocLand\AdminiMessages'NotA vailable html x 
<body> al 
<center> 
<p> 

<span style=" font-size: 14pt;font-family=sans-serif;"> | 
<b> 














reditCheck. spf 










ph <span style="color: goldenrod;">DocLand</span> 





p NotAvailable, html P Open 


+ Compie 


Remove From Project 






Directory 














version Control » Check In... 
Check Out 


Executing: cleartool desc -1 "C:\Doc¥. Un-Check Out w\DocAdminsDocLand'\ Admin Messages = 
version "C:\DocViews\jklobucher_Doc_v. Add to Source Control... min\Messages\Notavailable.html@@\ 
created 23-Mar-00.08:58:18 by Becke 
"made from flat file" 
Element Protection: 
User : BRILLIANT\BuildMeister : r 
Group: BRILLIANT\Domain Users : r 
Other: : r-- 


4 
ae Build] a Validate | i deploy] [Sk Find) Q} Version Control 














Line: 0 Column: 1 RO 





When you execute a version control command, resulting text messages display on the Version 
Control tab of the Output Pane. 
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Maintaining Todo lists 


Developing J2EE and Web Service applications can be quite a complex undertaking. It is 
sometimes hard to manage the work. With that in mind, Workbench provides the ability for you 
to maintain a Todo list that organizes and tracks your tasks. 


You maintain your Todo list in the Todo tab of the Output Pane. 


af Todo List 
[E =] SimpleEar spf in c:j2ee/ears/simpleEar 
5 EJBs 
B SimpleBean.spf in c: /2ee/ejbs/simplebean 
Wf Create remote interface 
Wf Create home object 
wf Add implementation code 
Fill in deployment descriptor 














=) wars 
(+) B SimpleVVar spf in c:/2ee/vars/simplewar 
Create deployment plan 
Deploy 


q > Build ] aw Validate | B: Deploy | [Find] [g] Todo 


You can: 





e Create Todo items 


e — Associate items with Workbench projects or mark them as independent of particular 
projects 


e Mark the completion status of items 
e Create a hierarchy of items 

e Reorganize the items in the hierarchy 
e Delete items 


In addition, various Workbench wizards and tools generate items in your Todo list to point you 
to areas where work needs to be done and to describe the nature of that work. 
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Working in the Todo tab 


When you first click the Todo tab, the Todo list is empty (unless you have run a tool or wizard 
that populates the list; see “Working with generated items” on page 42). 


Creating items The first thing you’ll do is add one or more items, which can be tasks or 


folders. 


> To add an item: 


1. Select the item following which you want to add an item and either press Ins or right-click 
and select Add Item. 


TIP You can also use Edit>Add Todo Item to insert an item at the end of the list, or press 
Shift+Ins to add the item as a child of the selected item. 


The Add Todo Item dialog displays. 


2. Enter the following information: 





Item 


Description 





Description 


Text to display for the item in the Todo list 





Note 


(Optional) Additional information about the item. This text displays 
as part of the item’s tool tip when the mouse pointer is over the item 





Add to open 
project 








If you want to associate this item with an open project, select the 
project from the list. 


If you select a project, the Todo item is added to the end of the list in 
the project’s folder (the folder is created if necessary). A project’s 
Todo folder is a top-level folder named: 


projectFile in pathToProject 


For example, if a project file is in 
c:\WorkbenchProjects\myEAR\MyEAR. spf, the project folder will 
be named: 


MyEAR.spf in c:/WorkbenchProjects/myEAR 





3. Click OK. 


The item is created. 


If you associated the item with a project, it is created as the last item in that project’s list. 
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If you did not associate the item with a project, it is created as a sibling following the 
selected item (unless no item was selected when you added the item, in which case the 
item is added as the first item in the list, or unless you added the item with Shift+Ins, in 
which case the new item is a child of the selected item). 


New items appear with the description you entered, along with a checkbox. The checkbox 
indicates the completion status of the item (see the next section). 


Editing items You indicate an item’s completion status, as well as revise its description and 
note, by editing the item. 


To edit an item: 


1. Select the item. 
2. Right-click and select Edit Item. 
The Edit Todo Item dialog displays. 


3. Update the information as appropriate. To indicate completion status, select a value from 
the Percent done listbox or type a value. 


4. Click OK. 


A faded checkbox indicates that the task has not begun. A half-filled checkbox indicates partial 
completion. A filled checkbox indicates completion. 
E SimpleBean.spf in c:j2ee/ejbs/simplebean 
Wf Create remote interface 
Wf Create home object 


wf Add implementation code 
Fill in deployment descriptor 


TIP You can also toggle an item’s completion status between 0 and 100 percent by selecting 
the item, right-clicking, and selecting Toggle Item(s) Done. If the completion status was 
Zero, it is set to 100; if it was non-zero, it is set to zero. 


Tool tips When you position the mouse pointer over an item, the item’s tool tip displays as: 


percent done; Notes: noteText 


Creating a hierarchy Todo lists can be hierarchical—items can contain other items. For 
example, you can create a folder of related tasks. 


> To create a hierarchy: 


e Move one or more items under another one by selecting the item(s) and either pressing > 
or by right-clicking and selecting Indent. 


The item becomes a child of its previous sibling, which is now a folder. 
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Similarly, to outdent one or more items, select them and press < or right-click and select 
Outdent. If an item no longer has children, it is no longer displayed as a folder. 


Moving items You can move an item around with drag and drop: Press and hold the mouse 
button on an item and move the item within the list. A horizontal line indicates where the item 
will be moved to. Release the mouse button to move the item. Moving a folder moves all of its 
contents as well. 


You can move an item anywhere in the list. 


TIP You can drag more than one item at a time as long as you drag as soon as you have 
selected the last of the multiple entries. (If you click after selecting the last entry, it 
reverts to a single selection. This behavior is a limitation of the JDK 1.3 version of the 
control used in the Todo tab and has been addressed in JDK 1.4.) 


Deleting items You can delete one or more items at a time. 


> To delete items: 


1. Select the items you want to delete. You can select a folder to delete it and all its contents. 
You can select multiple items anywhere in the list using Shift+Click and Ctrl+Click. 


2. Press Del or right-click and select Delete item(s). 
You are asked to confirm your deletion. 


3. Click Yes to delete the items. 


Using keyboard shortcuts The following keyboard shortcuts are supported in the Todo 




















tab: 
Keys Description 
Up Arrow Move up one item 
Down Arrow Move down one item 
Home Move to first item in list 
End Move to last displayed item in list 
Right Arrow Expand item if on a collapsed folder, otherwise move to next 
item 
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Keys Description 

Left Arrow Collapse item if on an expanded folder, otherwise move to 
parent 

Enter Toggle the expand/collapse state for item 

+ Expand all items 

- Collapse all items 

Ctrl+A Select all items 

Ctrl+/ Select all items 

Ctrl+\ Deselect all items 

ShifttUp Arrow Extend selection up 





Shift+Down Arrow 


Extend selection down 











Shift+Home Extend selection to start of list 
Shift+End Extend selection to end of list 
Ctrl+Up Arrow Move focus up one item without changing selection status of 


items 





Ctrl+Down Arrow 


Move focus down one item without changing selection status 
of items 


























Ctrl+Space Toggle selection status of item 

Shift+Space Select range of items from currently selected item(s) to item 
having focus 

> Indent selected items 

< Outdent selected items 

Ins Add item as sibling 

Shift+Ins Add item as child 

Del Delete selected items 
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Disabling the Todo feature If you don’t want to use the Todo feature, you can disable it 
by deselecting Enable Todo in General Preferences (Edit>Preferences). With Todo disabled, 
the Todo tab does not display and the Edit>Add Todo Item menu item is disabled. 


NOTE Even after disabling the Todo feature, your Todo list remains intact and will be 
displayed when you later reenable Todo. 


Working with generated items 


Various Workbench wizards and tools generate Todo items and add them to the corresponding 
project folder in your Todo list (remember that the Todo folder for a project is a top-level folder 
named projectFile in pathToProject). For example, the Servlet Wizard adds items about 
processing the servlet’s GET and POST requests and implementing any interface stub methods. 


@todo comments In addition to populating the Todo list with items, the wizards include 
@todo javadoc-style comments in the generated source files. These comments are of a finer 
granularity than the items generated in the Todo list. The Todo list would be too cluttered if all 
the @todo comments appeared in the list, but the @todo comments can be helpful to you in your 
detailed work. 


Actions in generated items Generated items are just like the items you create in the Todo 
tab, with one exception: 


A generated item might have an action associated with it. If a generated item has an action 
associated with it, you can invoke the action by doing either of the following: 


e Double-clicking the item 
e  Right-clicking the item and selecting the first menu item, which describes the action 


NOTE Ifan item has no associated action, the first menu item is Launch Action and it is 
disabled. 


Typically, the action is to open an associated file. For example, if you double-click the Todo item 
generated by the Servlet Wizard about specifying the servlet’s GET request, Workbench opens 
the servlet’s source file and positions the insertion point appropriately. 
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Specifying a debugger 


By default, when you select Edit>Launch Debugger or click the Launch Debugger toolbar 
button, Workbench opens a dialog asking you for information, then launches the SilverStream 
Debugger provided with Workbench. (For more information about using the SilverStream 
Debugger, see Chapter 12, “Debugger”.) 


Instead of using the SilverStream Debugger, you can also specify your own debugger so that 
when you select Edit>Launch Debugger, your debugger is launched with the proper 
command-line arguments. 


> To specify your own debugger to launch from Workbench: 


1. Select Edit>Preferences. 


2. Inthe Debugger command field in the General tab, specify the command line to launch 
your debugger, as described next. 
If this field is not empty, Workbench executes the specified command when you launch a 
debugger. If this field is empty, Workbench launches the SilverStream Debugger. 


3. Click OK. 


Specifying the command 


Specify the operating system command that Workbench should issue when you select 
Edit>Launch Debugger or click the Launch Debugger button. See your debugger’s 
documentation for information about how to invoke your debugger from the command line. 


You can include environment variables in the command by using the syntax $varname% or 
${varname}. Workbench substitutes the values of these variables when invoking the command. 


In addition to environment variables set at the operating system, you can also use environment 
variables that are predefined by Workbench: 


e You can use the same variables that the Workbench version control interface uses (see 
“Predefined environment variables” on page 33). 


The file-related environment variables (such as %_PATH%) refer to the file that is open 
and currently active in Workbench. 
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e Plus you can use the following two predefined variables: 





Variable Description 





%_CLASSPATH% The semicolon-delimited list of the classpath entries for the 
project and its subprojects 














%_SOURCEPATH% The directory containing the project file 





Using Ant 


Internally, Workbench uses Apache Ant when you build a project by selecting one of the Build 
commands on the Project menu (for more information about building Workbench projects, see 
“Compiling, building, and archiving” on page 87). You don’t need to know anything about Ant 
if you only want to do builds from the Workbench IDE. But Workbench also provides direct 
access to Ant so that you can accomplish the following: 


e Do project builds from the command line 


e Do your own customized Ant processing 


If you want to do either of these tasks, read this section to learn about Ant and how to use it. 


What is Ant? 


Apache Ant is a Java-based build tool, much like make but without make’s foibles. A couple of 
key differences between Ant and make are: 


e Instead of using makefiles, Ant uses XML-based buildfiles, which specify targets that 
define the processing that you want. 


e Instead of using shell-based commands, Ant is extended using Java classes. It comes with 
a built-in set of tasks, each implemented through a Java class. To define a new task, you 
define a new Java class that extends the Ant Task class. 


Ant is an open-source Jakarta subproject. To learn more about Ant, including details on defining 
your own tasks and creating buildfiles, see http://jakarta.apache.org/ant. 





Using Ant 


43 


1 Workbench Basics 





Using the Workbench Ant tools 


You can use Workbench tools to invoke Ant from the command line. There are two Ant-based 
executables in the Workbench bin directory: 


e xwbbuild, which allows you to build a Workbench project 


e  xwbant, which allows you to perform customized processing based on buildfiles (and 
possibly task classes) that you have created 


The difference between the two executables is that xwbbuild takes a Workbench project file as 
input, and xwbant takes an Ant buildfile. 


You invoke the tools from the command line. 


xwbbuild syntax Here is the command syntax for xwbbuild: 
xwbbuild projectFile WorkbenchTarget options 


where: 





Argument Description 





projectFile Path to the SilverStream project (.spf) file. This file specifies, 
among other things, the name of the Ant buildfile that builds and 
creates the archive(s) for your project. 





WorkbenchTarget Specify one of these project buildfile targets: 


¢ build—Builds and creates the archive(s) for the specified 
project (equivalent to selecting Project>Build and Archive) 


¢ rebuild—Rebuilds and creates the archive(s) for the specified 
project (equivalent to selecting Project>Rebuild All and 
Archive) 


e clean—Removes all files from the project’s build directory and 
deletes the archive(s) (no equivalent in the Workbench IDE) 














options See below for information on the options. 





xwbant syntax Here is the command syntax for xwbant: 


xwbant CustomizedTargets options 
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where: 
Argument Description 
CustomizedTargets Specify one or more of the targets you have defined in your 
buildfile 
options See below for information on the options. 














Options Here are the options you can provide with xwbbuild and xwbant: 



































Option Description 

-help Prints usage information 

-projecthelp Prints the description of the project (if one exists), followed by 
the targets defined in the buildfile 

-version Prints the version of Ant 

-quiet Be extra quiet 

-verbose Prints detailed information about the processing 

-debug Prints debugging information, including a mapping of tasks to 
Java classes and a listing of properties and their values 

-emacs (xwbant only) Prints logging information without adornments 

-logfile file Sends output to file, instead of to the screen. This option creates 
file if it doesn’t exist or overwrites file if it does exist. 

-logger class Specifies the class to do the logging. The default logger is 
org.apache.tools.ant.DefaultLogger. You can also specify another 
built-in logging class (look in ant.jar in the Workbench lib 
directory for provided classes) or specify a logging class you 
wrote yourself. 

See the Ant documentation at http://jakarta.apache.org/ant 
for details. 
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Option Description 





-listener class Adds class as a listener. A listener is notified when one of the 
following events occur: 


e A build is started 

e A build is finished 

e A target is started 

e A target is finished 
e A task is started 

e A task is finished 

e A message is logged 


There is no default listener. You can specify a built-in listener 
class (look in ant.jar in the Workbench lib directory for provided 
classes) or specify a listener class you wrote yourself. 


See the Ant documentation at http://jakarta.apache.org/ant 
for details. 





-Dproperty=value Overrides property value set in the buildfile. Properties are 
defined as <property> elements in the buildfile. 





-buildfile file (xwbant only) Specifies the buildfile to use. If this option is not 
specified, Ant uses build.xml in the current directory. 


(This option applies only to xwbant, because xwbbuild always 
uses the project buildfile that Workbench creates for you 
automatically.) 





-find file (xwbant only) Searches for buildfile file starting at the current 
directory. If it doesn’t find it in the current directory, it searches 
the parent directory, up to the root directory, until it finds file. 











If file is not specified, it searches for build.xml. 





Workbench modification to Ant The version of Ant shipped with Workbench is exactly 
the same as the version from Apache (use the -version command-line option to see the version 
number), with one exception: the Workbench Ant javac task supports a sourcepath attribute, 
which allows you to specify the -sourcepath argument to the compiler. Workbench generates 
buildfiles with this attribute, so Workbench buildfiles will not work with an unmodified Ant. 
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Examples 


xwbbuild examples The following command builds and creates the archive(s) for the 
myApp Workbench project (if changes have been made since the last time the project was built 
and archived). 


xwbbuild myApp.spf build 

The following command rebuilds all the files and creates the archive(s) for the myApp project. 
xwbbuild myApp.spf rebuild 

The following command removes all files from the build directory and deletes the archive(s). 


xwbbuild myApp.spf clean 


xwbant examples The following command performs the tasks defined for the default target 
in build.xml in the current directory. 


xwbant 


The following command performs the tasks defined for the purge target in build.xml in the 
current directory. 


xwbant purge 


The following command performs the tasks defined for the purge target in test.xml. If test.xml 
isn’t found in the current directory, Ant searches for it in parent directories until it hits the root 
directory. 


xwbant purge -find test.xml 
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Internationalization support 


This section describes Workbench’s support for internationalization. 


Specifying fonts 


If some international characters are not displaying correctly in Workbench (for example, they 
are displaying as boxes) or if the font mapping on your system is poor, you can specify different 
fonts for Workbench to use for its menus, labels, dialogs, and so on (note that the editors 
themselves are not affected by changes you make as described next). 


> To change the fonts used by Workbench: 


1. 
2. 


Exit Workbench. 


Specify alternate font names (and optionally sizes and colors) in the following lines in 
ide.props, which is in the Workbench Resources\Preferences directory: 


font -name 
font-size 
font -name 
font-size 
output-font-name = font-name 
font-size 
output-background-color = 
output-font-color = 


font-name-standard = 
font-size-standard = 
font-name-big = 
font-size-big = 


output-font-size = 
font-color 
font-color 


Font sizes are specified in points. Colors are specified as R,GB integer values; for example, 
255,255,255 is white and 0,0,0 is black. 


The standard font is used to display all standard-sized text, menus, labels, and so on. The 
default is 11-point Arial. 


The big font is used to display title text in wizards as well as buttons in wizards and 
dialogs. The default is 18-point Arial. 


The output font is used to display text in the Output Pane. The default is 12-point 
Monospaced, black on a white background. 


Sun recommends that you use Serif as the font name to provide the best font mapping on most 
systems. 
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Extending the Workbench toolset and services 


SilverStream eXtend Workbench is an extensible IDE for developing J2EE applications and 
Web Services. The standard toolset described in this documentation can be extended using the 
Workbench framework API. Contact your SilverStream representative for more information 
about extensibility. 
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2 Projects and Archives 





SilverStream eXtend Workbench helps you create J2EE components (including EJB JARs, JSP 
pages, servlets, and Java class files) to produce well-structured J2EE archives. Your work in 
Workbench is organized into projects. 


Working in a project involves editing sources (such as Java and data files), building classes, 
generating the archive, and deploying the archive. This chapter describes how to work with 
projects to create and manage J2EE components and archives. It includes the following 
sections: 

e About projects and archives 

e Organizing projects 

e Creating projects and subprojects 

e Populating projects 

e Viewing projects 

e Maintaining projects 

e Compiling, building, and archiving 


e Validating archives 


About projects and archives 


A project is a collection of source files that you work with in Workbench to create J2EE 
modules. A project can also be thought of as a series of rules that define how parts come together 
to create an archive. 


An archive is what gets generated from a completed project. A Workbench project can 
represent any of the following types of archive: 

e Enterprise archive (EAR) 

e Web archive (WAR) 

e Application client archive (JAR) 

e EJB archive (JAR) 

e Java class archive (JAR) 

e Resource adapter archive (RAR) 

e Deploy-only (non-buildable) archives 





2 Projects and Archives 





Workbench does not limit you to creating J2EE projects and archives. You can also develop and 
build nonarchive projects (projects that simply build other files) and utility projects (such as 
class files stored in a ZIP or JAR file) using Workbench. 


What a project includes A project can include: 


e Source code that will be compiled (the resulting files will be put into an archive) 


e Content files that you put directly into the archive (JSP pages, HTML pages, images, and 
so on) 


e A deployment descriptor for the project archive 
e — Server-specific deployment information 


e Other project files, called subprojects 


Project file Each project and subproject has a SilverStream project file (SPF file) that 
defines it. Workbench automatically creates this project file to store settings that you specify in 
Workbench. The project file defines how the project references subprojects, where files are 
stored on disk, and how files will be structured in the generated archive—and stores classpath 
entries and deployment settings. Changes you make to a project are automatically reflected and 
saved in the project file. When you add or move a component in a subproject, the change is 
updated in the subproject’s project file. 





CAUTION = There is no reason to directly edit the project file. All settings can be defined within 
Workbench. If you manually change the file incorrectly, you could compromise 
your ability to open the project associated with that file in Workbench. 
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Organizing projects 


When you create a project, you must specify what directories (or files) in your file system are to 
be included in the project and where to save the Java archive that is to be built by the project. 


You must also decide how to structure subprojects within a project. For example, a top-level 
EAR project might contain various subproject modules such as WARs and EJB JARs that define 
an application’s user interface, business logic, database access, and so on. 


Project design considerations 


J2EE and Web Service applications can be extremely complex, with many project design issues 
to consider. Your design decisions affect how to create the projects, subprojects, and 
components in Workbench that make up your application. 


LL) For more information about design considerations for J2EE and Web Service 
applications, see the chapter on developing applications in the Development Guide. 


Workbench supports almost any method for creating projects and components, including 
bottom-up (creating components first and then Workbench projects and subprojects) and top- 
down (creating projects and subprojects first and then components). In most cases, you should 
follow a top-down approach—first create the project and subproject structure and then create 
new components and add them (and any existing components) to your project. 


LL) For information about creating an entirely new project, see “Creating projects and 
subprojects” on page 6. For information about creating a project that contains existing source 
files and components, see “Working with existing source files” on page 14. 


Project directory structure considerations 


Workbench provides a lot of flexibility in defining the directory structures for your project’s 
source files and the archive built from those source files. 


Directory structure of your source files The directory structure of the source files on 
your file system does not need to match the directory structure of the generated files in the 
archive. For example, files in different source directories can be assigned to the same directory 
in the archive. To simplify development, however, you may want to set up your project 
directories to mimic the directory tree structure that will group J2EE components into archives. 
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You could create your project source file directory structure so that the project (SPF) file is 
located at the root of that directory structure and then create a project sre directory (at the same 
level as the project file) in which you can place all of the project source code. For example: 


myWebProject \ 
myProject.spf 
sre\ 
dbAccess\ 
addItem.java 
changeItem.java 
deleteItem.java 
queryDB.java 
loginProcessing\ 
login.java 
user.java 





useriInterface\ 
intro.jsp 
login.jsp 


loginError.jsp 
welcome.jsp 


When creating an enterprise archive (EAR) project with multiple subprojects (JARs, WARs, 
EJB JARs, and so on), it may be easiest to have all the project files at the same level, and have 
the sources of each subproject in separate sre subdirectories. For example: 


myWebProject \ 
myProject.spf 
myProjectDB.spf 
myProjectLogin. spf 
myProjectUl.spf 
src\ 
dbAccess\ 
addItem.java 
changeItem.java 
deleteItem.java 
queryDB.java 
loginProcessing\ 
login.java 
user.java 





useriInterface\ 
intro.jsp 
login.jsp 


loginError.jsp 
welcome.jsp 


If your project package structure becomes too cumbersome, you can always move the 
subproject components into separate subdirectories. You can structure Workbench projects 
using a single or a combined source tree. 
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C For more information on project settings, see “Managing project content settings” on 
page 30. 


Directory structure of an archive The internal directory structure of your J2EE archive 
depends on the archive type. Each type of archive has an XML descriptor that conforms to a 
particular DTD. 


For example, when creating a Web archive (WAR), you must specify which files are accessible 
directly through an URL (such as JSP pages and servlets) and which files are not (such as 
supporting class and archive files). J2EE specifies that you locate files that are not to be made 
accessible through an URL in a WEB-INF directory in the archive directory structure. This 
WEB-INF directory should be located beneath the archive root directory and typically includes: 





File or directory Contents 





web.xml A required deployment descriptor file that tells the application 
server how to interact with the Web application 

















WEB-INF/classes/ A directory containing the compiled Java class files for the 
application 
WEB-INF'lib/ A directory containing the JAR files used by the application 





The JSP pages that are URL-accessible typically are located in the root directory of the archive. 
You may want to hide some JSP pages (such as those used by Struts) from URL access. Files 
under the WEB-INF directory are by default not accessible via URL, although you can 
configure them for URL access. The locations of other files are up to you. 





CAUTION When you create the WEB-INF directory, you must ensure that the directory name 
is in all uppercase text. 





For more information This section has provided only a glimpse into some of the issues 
you may encounter when designing your source file and archive directory structures. 


LL) For more information about specifying archive directory structure and packaging 
archives, see the Sun J2EE Blueprints document. 


G For information about how you can specify source and archive directory structures in 
Workbench, see “Managing project content settings” on page 30. 
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Creating projects and subprojects 


A project (or subproject) can be an EAR, EJB JAR, WAR, RAR, JAR, deploy-only archive, or 
application client. As you create a project, you define a project name and a location for your 
source files. Workbench maps all of these source files to names and locations that you define for 
the archive. 


The following steps (using the New Project Wizard) apply to each type of project, with 
exceptions noted. 


LL) For information on organizing the development workspace before beginning a project, 
see “Project directory structure considerations” on page 3. 


> To create a project: 


NOTE Ifyou are creating a subproject, you must open the parent project in Workbench before 
starting this procedure. 


1. Select File>New Project. 
The New Project dialog appears: 


Choose the project type, or select Deploy-only if you 
you want to create a project for deployment of an 
existing archive file that you don't want to build. 


6 EAR WAR 
4 Enter 5 Web Archive 


Enterprise Archive 


2 EJE Tj] CAR 
4 = Application Client Archive 


Enterprise JavaBean Archive 


Resource Adapter Archive Java Archive 


i | Deploy-only 
Non-buildable Archive 





















Cancel Help 


2. Choose a project type and click OK. 


e Ifyou want to create a nonbuildable archive, select Deploy-only. For detailed 
instructions, see “Creating a deploy-only project’ on page 12. 
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e If you are creating an EJB JAR and EJB client JAR pair, you should first create the 
parent WAR or EAR for both so that both projects can be open at once. For detailed 
information on the relationship between the EJB JAR and the client JAR, see 
“Specifying the EJB JAR configuration” on page 125. 


e Ifyou want to create a project that includes a completed archive (along with its source 
code) from a third-party source, choose a project type and follow the instructions in 
“Working with existing source files” on page 14. 


NOTE The following New Project Wizard panels (to create a WAR) apply to each type 


of project. 


Enter the name and location (directory path) for 
the project, the archive file, and the deployment 
descriptor (if relevant). If this is a J2EE project, 
select the desired J2EE version. (To use an 
existing archive as-is, create a deploy-only 
project instead.) 


Project Name: 


Forecast 


Project Location: 


F: WorkbenchProjects'Forecast H 





Archive Name (e.g. office war): 


Forecast 


Archive Location (directory): 


E: WorkbenchProjects\Forecast w 





Deployment Descriptor Name: 


[veb xml 


Deployment Descriptor Location: 


F:WorkbenchProjects'ForecastWEB-INF w 
Project J2EE Version: Jee 1.3 (war 2.3) z] 








E >) Cancel) Help 
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3. Specify project information as follows: 





New project setting What you do 





Project Name Specify the name you want to use for the project (the .SPF 
extension is automatically appended). This name appears in 
the Source Layout. 


As you enter a project name, the archive name is filled in 
automatically. You can keep the same name for your archive 
or enter another one. 





Project Location Specify the directory where you want the project (and other 
source files) to be located. Workbench creates a 
SilverStream project file (with an .SPF extension) in the 
project location. 


As you enter a project location, the rest of the new project 
settings are filled in automatically. You can change these 
settings. 


You can click the ellipses beside the Project Location field 
to select a location, or type the project directory. 


If you specify a project location directory that does not 
exist, the wizard prompts you to create it. 


If you do not specify an absolute path, the wizard locates the 
project under the Workbench bin directory. 





Archive Name Specify the name of the archive file that will be generated. 
The resulting name will appear in the Archive Layout. An 
extension based on the archive type will automatically be 
appended to the name. You can keep the default archive 
name (that matches the project name) or enter a new one. 


To create a project based on an existing archive or to create 
a deploy-only project, enter the name of the existing archive 
that you want to include. 


G For information about creating projects based on 
existing archives, see “Working with existing source files” 
on page 14. For details about deploy-only archives, see 
“Creating a deploy-only project” on page 12. 
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New project setting What you do 





Archive Location Enter the location of the project archive or accept the 
default (the project root directory). 


The archive location appears in the Archive Layout of the 
Navigation Pane after the project has been created. 





Deployment Descriptor | The wizard fills in a deployment name (based on the project 
Name type) after you enter a project location. Each archive stores 
its own set of deployment information in this XML 
deployment descriptor file source file. Workbench creates 
the default deployment descriptor name and location (based 
on archive type) when you build and archive the project. 


In most cases you should accept the default name and 
location. 


If you are converting an existing archive project (by 
creating a Workbench project file), enter the name of the 
deployment descriptor file on disk. 


If you want to have multiple J2EE subprojects of the same 
type sharing the same deployment descriptor directory 
location, see Deployment Descriptor Location (just below). 


The deployment descriptor name you enter here affects only 
the source file name—not the file name that is used in the 
JAR. When Workbench builds the archive, it includes this 
deployment descriptor file in the archive using the standard 
location defined by the J2EE specification for the archive 


type. 


G For more information on deployment descriptor 
names, see Chapter 3, “Archive Deployment” and Chapter 
10, “Deployment Descriptor Editor”. 
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New project setting What you do 





Deployment Descriptor | Enter the location of the deployment descriptor or accept 
Location the default. Each archive type uses a required J2EE default 
directory location. 


If you are converting an archive project, enter the location 
of its deployment descriptor. 


In most cases you should accept the default name and 
location. However, if you want to have multiple J2EE 
subprojects of the same type sharing the same deployment 
descriptor directory location, you should either enter a 
different source file name for each deployment descriptor or 
create a separate directory structure beneath the root 
directory for each descriptor. 


If you specify (or if Workbench finds) a deployment 
descriptor in the project source location matching the one 
you specify, it prompts whether or not you want to use the 
existing deployment descriptor. If you answer no, you will 
need to change the deployment descriptor name or location 
before continuing. 


G For more information on deployment descriptor 
default names and locations, see Chapter 3, “Archive 
Deployment” and Chapter 10, “Deployment Descriptor 
Editor”. 





Project J2EE Version Specify the version of J2EE for this project. 


LL) For information on targeting your application at an 
appropriate version of J2EE, see the chapter on handling 
J2EE versions in Getting Started. 














NOTE All settings on this wizard panel are required—except the two deployment 
descriptor fields and the J2EE version, which are not required (or displayed) for 
the Java or deploy-only archive. 

4. Click Next. 


5. If you have a project currently open in Workbench, the wizard asks if you want to add the 
new project as a subproject to that project or one of its subprojects. 
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To make this new project a subproject of the 
currently open project (or any of its subprojects), 
check the box and specify whether you want to add 
the archive itself, or its contents. 

















[V Add this project to the current project 





File: F: WorkbenchProjects\Forecast'F orecast spt 


Add to project: Sandbox z] 


JV Include in parent archive 


( Add the generated archive of the subproject to the parent archive. 
© Add the contents (individual files) of the subproject to the parent archive. 


@ Add the child archive to the root of the parent archive. 


© Add the child archive at this location: | 





Cancel 





Help 


If no project is currently open in Workbench, this panel does not appear. 


If you do not want to create this project as a subproject, deselect Add this project to the 
current project and click Next. (You can proceed to Step 6.) 


To create the project as a subproject of another project: 
e Select Add this project to the current project. 


e Select the parent project under Add to Project. This list contains the currently open 
project and all subprojects associated with it. 


e Select Include in parent archive. 


e Ifyou want to add the generated archive of this project to the parent archive (as 
opposed to adding all of the generated files), select Add the generated archive of the 
subproject to the parent archive. 


If you want to add the generated files (instead of the generated archive) of this project 
to the parent archive, select Add the contents (individual files) of the subproject to 
the parent archive. 
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e The wording of the next two options vary, depending on whether you choose to add the 
archive or the individual files to the parent archive. 


In either case, you are asked whether to add the archive or files to the root of the 
parent archive or to specify some other location in the parent archive. 
e Click Next. 


6. The wizard summarizes the project details. Click Finish to create the project. 


You can see the new project in the Project tab in the Navigation Pane. If necessary, you can view 
or change project names and locations using the Project Settings dialog. 


Once you have defined how your Workbench projects and subprojects will be structured, you 
can start adding source directories and files to a project, as described in “Adding to projects” on 
page 18. 


Creating a deploy-only project 


Workbench allows you to validate and deploy an archive for which you have no source code by 
first creating a deploy-only project for the archive. 


For example, if you received a completed EJB JAR archive from a third party without any 
source code, you could create a deploy-only project for it. You cannot add to a deploy-only 
project. 


NOTE Ifyou receive a completed archive along with its source code, you should create a 
regular Workbench project, not a deploy-only project. 


An EAR can contain both deploy-only and regular projects. For example, you can create an 
EAR containing an EJB JAR that you don’t have the source for and a regular WAR that calls that 
EJB JAR. 


LL) For more information, see “Working with existing source files” on page 14. 


How you tell that a project is deploy-only When you open a deploy-only project: 

e The build commands on the Project menu are disabled. This prevents you from 
accidentally overwriting the archive—which you would be unable to recreate. 

e The Contents tab of the Project Settings dialog is replaced by the following message: 


The archive is deploy only. Its contents cannot be modified or examined. 


> To create a deploy-only project: 


1. Select File>New Project. 
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The New Project dialog appears: 


Choose the project type, or select Deploy-only if you 
you want to create a project for deployment of an 
existing archive file that you don't want to build. 


6 EAR WAR 
4S Enter & Web Archive 


Enterprise Archive 


ais B: 
Application Client Archive 


Enterprise JavaBean Archive 


Resource Adapter Archive Java Archive 


i | Deploy-only 
Non-buildable Archive 








G Gancel Help 





2. Select Deploy-only and click OK. 


This is a deploy-only project for an existing 
archive that you want to deploy but do not want 
to build. 

Please select the archive file on which to base 
the project, and check that the correct version is 
selected for the project type. 








Archive File: 

[WorkbenchProjects'SandboxiSandbox.war E 
Project Type: ‘AR (war 2.3) ve 
Project Name: 

Project Location: 

FEWorkbenchProjects\Sandbox N 





Agak jlgziz Cancel Help 
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3. In the New Project Wizard, specify project information as follows: 





Deploy-only project 








settings What you do 

Archive File Enter or browse to the deploy-only archive file on which 
you wish to base the project. By default, the Project 
Location is set to the directory of the specified file when 
you select the archive. 

Project Type Make sure the archive type and J2EE version are correct. 





Project Name 


Enter a name to identify the deploy-only project. 
Workbench creates a SilverStream project file (with an .SPF 
extension) in the project location. 





Project location 








Specify where you want the project to be located. The 
location identifies the project root directory. 


The Project Location is set to the directory of the specified 
file when you select the archive, but you can change it. 








4. Click Next. 


5. If you have a project open, the wizard asks if you want to add the new project as a 
subproject of that project or one of its subprojects. For more information, see Step 5 under 
the preceding procedure for creating a project. 


Otherwise, the wizard summarizes the project details. 


6. Click Finish to create the project. 


You can see the new project in the Project tab in the Navigation Pane, but you cannot edit its 
contents. If necessary, you can view or change project names and locations using the Project 


Settings dialog. 


Working with existing source files 


There are several ways you can use J2EE components and modules created with third-party 


tools in Workbench: 


e Ifyou want to create a nonbuildable archive that you validate and deploy in Workbench, 
you must create a deploy-only archive (a completed archive without any source code). For 
detailed instructions, see “Creating a deploy-only project” on page 12. 
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e Ifyou have source code files and want to build an editable archive, you should create a 
regular Workbench project file as described below. 


The following procedure describes one (directory-centric) approach where the resulting archive 
structure mirrors the directory structure of the source files. You can create a new project ina 
deploy-only archive using this same approach. The only difference is that you will not be able 
to later add source files to this type of archive. 


> To create a project that includes existing source files: 


1. Create a source directory structure and locate all your source files there. 


When including existing archives, you may want to add the entire directory structure, 
since it is easier to maintain your project source files if you add directories rather than 
individual files. Once you have set up a project directory, files you add to it later will be 
automatically included in the resulting archive. 


2. Create a Workbench project, as described under “Creating projects and subprojects” on 
page 6. 

3. Add the source directory you created in Step 1 to the project, as described under “Adding 
to projects” on page 18. 
Once you have added the source directory to the project, any changes you make later are 
automatically included in the archive and you avoid possible duplication of files. 


Populating projects 


Once you have a project, you can add components and subprojects to it. How you begin a project 
depends on whether you are creating a completely new project (no files, directories, or modules 
exist yet) or bringing existing J2EE components (created using an external IDE) into 
Workbench so you can add them to the project and deploy the archive. 


LL) For more information, see “Project design considerations” on page 3 and “Working with 
existing source files” on page 14. 


Creating source files 


As you create source files in Workbench, you can group them under whatever project directories 
you want. You can create the source file and then add it to a project or open a project and then 
add the source file. Your project settings specify where files are located in the archive. 
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Source files include: 


e Source code, such as Java files that will be compiled into an archive 


e Content files that will be put directly into the archive, such as JSP pages, XML files, 
HTML pages, images, and so on 


Typically, you want to create a directory and add that to the project before creating source files. 
When you add a directory to the project, any source files you create in that directory and in its 
subdirectories are automatically added to the project. 


LL) For details about adding directories to a project, see “Adding an entire directory” on 
page 21. 


When creating source files using the component wizards, any directories you specify are 
automatically added to the project. 


> To create a source file: 


1. (Optional) Open the project you want to add the file to. 
2. Select File>New. 
The New File dialog appears. 


RZ 7 
o~ New File x] 


Choose file type: 










Web Services | XML | 














B EJB Servlet 
Create a new Enterprise JavaBean Create a new Servlet 
w JSP {a} Java file 
Create a new JavaServer Page Create a new Java class file 
Ka} JavaBean {a} Tag handler 
Create a new JavaBean class file Create or modify a Tag handler library 
Generic text file ea} SilverStream Deployment Plan 
Create a generic empty file Create a new SilverStream deployment plan 
(aa) Deployment Descriptor 
Create a new deployment descriptor 













[ Use wizard 





Or Gancell Help 





3. On the J2EE tab, choose a file type and click OK. The wizard for that file type starts. 


The wizards have built-in J2EE logic that facilitates the creation and deployment of well- 
structured J2EE components. 


When the wizard finishes, a source editor containing the wizard-generated file opens in 
the Edit Pane. 
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(AM) 


(RA 


Q 












































Q 


For more information see: 
“EJB Wizard” on page 117 
“Servlet Wizard” on page 161 
“JSP Wizard” on page 156 
“Java Class Wizard” on page 167 
“JavaBean Wizard” on page 172 
“Tag Handler Wizard” on page 176 


For information about source editors in Workbench, see Chapter 6, “Source 


Editors”. 


For information about the deployment-related wizards, see Chapter 10, 


“Deployment Descriptor Editor” and Chapter 11, “Deployment Plan Editor”. 


For information about the Web Service-related wizards, see Chapter 5, “Web 


Service Wizard” and Chapter 8, “WSDL Editor”. 
For information about the XML-related wizards, see Chapter 7, “XML Editors”. 


> To create a source file without using a wizard: 


1. (Optional) Open the project you want to add the file to. 
2. Select File>New. 
The New File dialog appears. 
3. On the J2EE tab, choose Generic text file or Java file. 
4. Deselect Use wizard and click OK. 
A text editor containing a blank file opens in the Edit Pane. 


(J For information about source editors in Workbench, see Chapter 6, “Source 
Editors”. 
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Adding to projects 


You can add source files, directories, and subprojects to an existing project. 


Adding source files to a project 


The following procedure describes how to add files and directories to a project. 


To add files and directories to a project: 


1. 
2. 


Open the project you want to add to. 
Select Project>Add to Project. 


LL) For other methods, see “Other ways to add files and directories to a project” on 


page 20. 


Choose whether you want to add a file or directory. 


Typically, you add directories to your project rather than individual files. 


Navigate to and choose the file or directory you want to add. 
Click Open or OK. 


3% Add to Project x] 
File: [:WorkbenchProjects\CalcWARClientiisps 


Add to project: Sandbox z] 
I Include subdirectories 


C Add the files to the root of the archive. 


(© Add the files to the archive at this location: JrorkbenchProjects/CalcWARClientiisps 
Advanced => | 





OK Cancel Help 
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6. Set the following options to specify how the file or directory will be added to the project 
and where you want it to be located in the archive: 





File and directory 
setting Description or action 





File Shows the (editable) path of the directory or file that you are 
adding to the project. 





Add to project Select the project that the specified item will be added to. 
Only the top-level open project and associated subprojects 
appear on the menu. 





Include subdirectories When adding directories, select to add the contents of the 
subdirectories as well as those of the specified directory. 





Add the file(s) to the Select to add the specified files to the root of the archive. 
root of the archive Clicking this option means you cannot remove the contents 
from the project without manually deleting the contents 
from the file system. 





Add the file(s) to the Select to add the specified item to a specified location other 
archive at this location: | than the archive root. 


You can also use relative paths or environment variables 
when locating shared project files or referring to files 
located outside the project’s directory structure. 


LL) For more information, see “Using environment 
variables” on page 30 and “Using relative paths” on 
page 31. 














7. Ifyou are adding a directory to your project, click Advanced. 
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The following project entry settings let you specify how to include Java sources (of the 
files or directories) in the generated archive. 








Advanced setting Description or action 
Include Java source Select if you want to include sources files in the generated 
files in archive archive. For most production environments, you will not 


want to include Java source code. 





Add the files to the root | Select to store source files in the archive root directory. 

of the archive Clicking this option means you cannot remove the contents 
from the project without manually deleting the contents 
from the file system. 





Add the files to the Select and then specify a directory in which to store source 
archive at this location | files. 














NOTE You can also edit these project entries in the Edit archive entry dialog (by 
clicking Edit in the Contents tab of the Project Settings dialog). 


8. Click OK to add the file or directory to the project. 
To see (or edit) how contents have been added to your project, click the Contents tab of 
the Project Settings dialog. 


LL) For information about editing project contents, see “Managing project content settings” 
on page 30. 


Other ways to add files and directories to a project Using Project>Add to Project 
is only one way to add files and directories to a project. Other ways include: 
e Clicking Add Entry or Add Directory on the Contents tab of the Project Settings dialog 


e Using the popup (right-mouse) menu on the file or directory you want to add in the 
Directory tab of the Navigation Pane and choosing Add to Project. 


Using this technique you can add multiple files at the same time: press Ctrl+Click to add 
multiple noncontiguous files; press Shift+Click to add multiple contiguous files. 


Notes about adding individual files You typically add entire directories to your project. 
However, you can also add: 


e The entire contents of a directory 


e Individual file(s) in a directory 
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If you add a subproject as contents rather than as an entire project to a top-level project, the 
name will appear grayed out and within parentheses in the Archive Layout view of the 
Navigation Pane. 


Refreshing the Navigation Pane Workbench automatically updates the contents of the 
Directory and Project tabs in the Navigation Pane when you make changes in Workbench. If you 
make changes outside Workbench, select View>Refresh or press F5 to see the changes. 


Adding an entire directory 


When you add a directory or directory tree to a project (as described in “Adding source files to 
a project” on page 18), the structure of the files and directories in the archive matches the layout 
of the files and directories of your (on-disk) source directories. 


When you specify an entire directory, anything you later change, add, or remove within that on- 
disk directory is automatically reflected in the project. To relocate archive files, you can simply 
move them from the existing source directory structure on your file system. Any such changes 
will be automatically reflected in your project, provided that you keep them within the source 
directory structure used by the project. 


What gets excluded When you add the entire directory to a project, Workbench excludes 
the following types of files from the generated archive: 

e Any file ending in ~ 

e Any file starting and/or ending with # 

e Any file starting and/or ending with % 

e Any file named cvsignore 

e Any files in a directory named CVS 


e Any files ending in JAVA (by default, though you can choose to include Java files when 
adding the directory) 


e Any autosave and backup files ending in SAV and BAK 


These are generally backup or version control information files and don't belong in the 
generated archive. 


Adding subprojects to a project 
The following procedure describes how to add a subproject to a project. 


LL) For details about creating subprojects, see “Creating projects and subprojects” on page 6. 
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> To add a subproject to a project: 


Open the project you want to add to. 
Select Project>Add to Project>Subproject. 


LL) For other methods, see “Other ways to add files and directories to a project” on 
page 20. 

A file selection dialog appears. 

Navigate to and choose the subproject file you want to add. 


Click Open. The Add to Project dialog appears. 


ZZ Add to Project x] 
File: [:WorkbenchProjects\SandboxiSandbox.spt 


Add to project: [Director z] 


|V Include in parent archive 
(@ Add the generated archive of the subproject to the parent archive. 


© Add the contents (individual files) of the subproject to the parent archive. 


(Add the child archive to the root of the parent archive. 


© Add the child archive at this location: | 





Cancel, Help 


In the Add to project field, select the project that the specified archive will be added to. 
NOTE Only the top-level project and any associated subprojects appear as choices. 
Select Include in parent archive to add the contents of the subproject to the parent 
archive. 

If Include in parent archive is not selected, the subproject will still be built before the 
parent project, but none of its contents will be included in the parent archive. 

If you want to add the generated archive of this project to the parent archive (as opposed to 
adding all of the generated files), select Add the generated archive of the subproject to 
the parent archive. 

If you want to add the generated files (instead of the generated archive) of this project to 


the parent archive, select Add the contents (individual files) of the subproject to the 
parent archive. 
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The wording of the last two options vary, depending on whether you choose to add the 
archive or the individual files to the parent archive. 


If you selected Add the generated archive of the subproject to the parent archive, set 
one of the following options to determine how the specified archive will be added to the 


parent archive: 





Subproject setting 


Action 





Add the child archive to the root of the 
parent archive 


Select to add the specified archive to the 
root directory of the parent archive. 





Add the child archive at this location 








Select (and enter a location) to add the 
specified archive to a location other than 
the root directory of the parent archive. 


You can also use relative paths or 
environment variables when locating 
shared project files or referring to files 
located outside the project’s directory 
structure. 


LL) For more information, see “Using 
environment variables” on page 30 and 
“Using relative paths” on page 31. 








If you selected Add the contents (individual files) of the subproject to the parent 
archive, set one of the following options to specify how the subproject contents (rather 
than the subproject’s generated archive) will be added: 





Subproject setting 


Action 





Add the files to the root of the parent 
archive 








Select to add the archive contents to the 
root directory of the parent archive. 
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Subproject setting Action 
Add the files to the archive with this Select and then enter a prefix to add the 
prefix: archive contents to a directory with the 


specified prefix. 


You can also use relative paths or 
environment variables when locating 
shared project files or referring to files 
located outside the project’s directory 
structure. 


LL) For more information, see “Using 
environment variables” on page 30 and 
“Using relative paths” on page 31. 














9. Click OK to add the child archive (or files) to the parent archive. 


TIP ‘To see how contents have been added to your project, click the Contents tab of the 
Project Settings dialog. 


G For more information about adding project contents, see “Modifying project entries” on 
page 31. 


Viewing projects 


You use the Project tab in the Navigation Pane to view projects. You can view projects in three 
ways to see how directories and files are organized on the file system and in the archive: 

e Source Layout view 

e Archive Layout view 


e Archive Contents view 


Source Layout view The Source Layout view reflects the organization of the project’s 
files and directories on your hard disk. Subprojects are listed at the top level as folders. 
e  Subprojects added as archives and as contents are both shown using the project name 


e  Subprojects excluded from the parent archive are shown grayed out using the project 
name 
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The Archive views The Archive Layout view and Archive Contents view both reflect the 
organization of the archive that will result from building the project. The Archive Layout view 
presents a development-oriented picture of how the project files and directories will be 
organized in the resulting archive, while the Archive Contents view is the closest representation 
of what will be in the generated archive. The differences between the two views are: 


e Archive Layout shows the project’s source files (.java files), even though the archive 
actually contains compiled files (.class files). Archive Contents shows compiled files 
since they are what is in the archive (double-clicking a .class file opens the corresponding 
source file in the Java Editor for editing, unless the java file can’t be found, in which case 
the .class file is opened in the Class Viewer). 

e Archive Layout lists all subprojects, even those subprojects that have been added as 
contents (as opposed to being added as archives) and those subprojects excluded from the 
parent archive, to give you an idea of how the projects are organized. 


e  Subprojects added as archives are listed as the archive that they generate 
e  Subprojects added as contents are displayed grayed out using the name of the project 
e  Subprojects excluded from the parent archive are shown grayed out, using the name of 


the archive or the project name, depending on which state would result from 
reincluding the subproject in the parent archive 
In the following screen, the ResourceSet subproject has been added as an archive, so 
displays with its archive name. The Custom subproject has been added to the project as 
contents, so is grayed out. The Sandbox subproject has been excluded from the parent 
archive, so it too is grayed out. 








H-E META-INF 
E library 


{+} ContentMgmtService.war 


Ej Portal.war 
(ej ResourceSet.war 
[+h (Custom. spf) 











Archive Contents lists subprojects as follows: 
e  Subprojects added as archives are displayed using archive names 


e  Subprojects added as contents are represented by the content itself, since that is how 
they will appear in the parent project’s archive 


e  Subprojects that are excluded from the parent archive are not represented at all 
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TIP 


The following screen shows the Archive Contents view of the same project shown above. 





View using POOLEL >| 
5j & Director .spf 
e0] META-INF 
E} fa library 
f+ ContentMgmtService, war 
ey Portal. war 
Gt ResourceSet.war 
-E wEB-INF 











Archive Contents shows each inner class in a .java file, in addition to the file’s primary 
class. 


You can see a file’s complete name and path by positioning the mouse over it in the lower 
subpane of the Directory or Project tab. Workbench tool tips are particularly useful in an 
Archive view for comparing a file as it exists in the archive (such as WEB-INF/web.xml) 
to its location on disk (such as C:\dev\Aries\web.xml). 


Maintaining projects 


Your open project may be your top-level project or it may be a subproject. Workbench allows 
you to manage the settings of any open project by adding or modifying files, directories, 
subprojects, paths, classpaths, and so on. You can modify a project by: 


Opening a project 

Managing general project settings 

Managing project content settings 

Removing files, directories, and subprojects from projects 


Renaming a project 


G For more information on team development and design considerations, see the 
Development Guide. 
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Opening a project 


To open a project, open the project file (with the .SPF extension). Changes you make to a top- 
level project file are automatically saved in that file along with any other subprojects that are 
part of the same top-level project. 


You can open multiple projects at a time, as long as they are all part of the same top-level 
project. For example, you can simultaneously open an EAR, a WAR, an EJB JAR, and a 
application client provided they are all part of the same top-level EAR. 


NOTE Whenever you add a component or subproject, the project file is automatically saved. 
The only time you need to explicitly do a save is when you make changes to a source 
file using one of the editors. 


> To open a project: 
1. Select File>Open Project. 
2. Navigate to the project directory. 
3. Select the project file (SPF) and click Open. 
In the upper left, the Navigation Pane displays the Archive Layout of the project. The files 


are displayed in the lower subpane of the Navigation Pane. 


TIP You can also navigate to the project file in the Directory tab and double-click the file to 
open it. 











View using: archive layout z] 
7 Start sp’ 











BB contribute jsp 

[J contriputeFailed jsp 
F contributeResutt jsp 
a index jsp 

a menujsp 

a select jsp 

a selectFailed jsp 
F) selectResults jsp 
a today jsp 


Be oe 
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Managing general project settings 


The General tab on the Project Settings dialog lets you view information about the open project 
and change the location of the source directory that stores the project class files. 


> To view or modify project settings: 


1. 
2. 
3. 


Open the project. 
Choose Project>Project Settings. 


Select the General tab and view or modify any of the options as follows: 


3% Project Settings x] 


Project: E 













General | Contents | Classpath/Dependencies | 


Project type: WAR 
Project directory: © C:WVorkbenchProjects'ProverbStart 
Project file: C:WVorkbenchProjects'ProverbStart'ProverbStart spt 


Project version: J2EE 1.2 WAR 2.2 


[T Use source directory for classes 


Classes directory: puilc\ProverbStart-classest Browse... | 
Archive file path: ProverbStart.war 





Gancel 





Help 





























Setting Description or action 

Project Lists the project currently open. 

Project type Lists the type of project you created. 

Project directory Lists the open project’s root directory. 

Project file Lists the file name and location of the open project. 
Project version Lists the J2EE version 
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Setting 


Description or action 





Use source directory for 
classes 


Specifies whether you want to compile Java files into the 
same directory as their corresponding source files. 


By default, the check box is not selected and classes are 
compiled into the build directory beneath the project’s 
root directory. You can change the build directory by 
changing the Classes directory setting (below). 


If you select the check box, all project classes are 
generated into the source directory along with with their 
source files. 





Classes directory 


Lists the root of the build directory where the project’s 
compiled class files will be located. Workbench writes the 
generated classes to this directory when it builds the 
archive. 


The default is build/project_name-classes beneath the 
project’s root directory. You can change the directory by 
typing or browsing to a different directory. 





Archive file path 








Lists the name and location of the archive. Workbench 
writes the generated archive to this location, which is 
relative to the project root. 


You defined this location when you created the project. 
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Managing project content settings 


You specify how files and directories are organized in the project’s Source and Archive Layouts 
using the Contents tab of the Project Settings dialog. 


$= Project Settings x] 
Project: [ProverbStart z] 


General Contents | Classpath/Dependencies | 


Source location | Archive location 


WVEB-INF/ 

|<Root of Archive> 

WWEB-INF /classes/ 
\WEB-INFiclasses/comiproverbi 


Help 





This dialog lets you define files and directories in terms of project entries in a table. Each entry 
defines the location of a source file or directory in the file system and how it is added to the 
project archive. 


When specifying file and directory locations, you can use environment variables and absolute 
and relative pathnames. 


Using environment variables 


Windows environment variables are useful when a development team shares files (such as a 
single project file or JARs) that are located outside the project’s directory structure. A shared 
project file must be able to refer to files or directories that exist in different locations on different 
team members’ machines. You typically use environment variables in Workbench for locating 
files that are not under the project’s root directory. 


You set the environment variables by using the Environment tab in the Windows System control 
panel. You reference the variables in Workbench using the following syntax: % varname% or 
${varname}. You can use Workbench variables: 


e When editing or adding to a project using the Add to Project dialog 


For example, change d: \utilproj\util.spf to SUTIL_PROJECT_DIR%\util.spf or 
${UTIL_PROJECT_DIR}\util.spf 
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e When editing your project's classpath using the Classpath/Dependencies tab of Project 
Settings dialog 
For example, add UTIL_PROJECT_DIR%\util.jar or ${3RDPARTYJARS}\helpers.jar 
to the classpath to include a subproject. 





NOTE You need to restart Workbench before the value of an environment variable (set in the 
Windows Control Panel) takes effect. 


It may often be easier to use a relative path (instead of an environment variable) to locate any 
shared project files that are in the project's directory tree. For example, you could specify a sre 
directory to refer to the directory named sre under your project's directory. 


Using relative paths 


The project root is the directory on your hard disk that contains the project file—for example: 
C:\MyProj\Proverbs. You can use relative paths when referring to files within the project’s 
directory—for example, to specify up two directory levels: .\..\mydir\file.jar. 


By default, any paths you specify for files or directories are set relative to the project’s root 
directory, provided the source directories are nested beneath the root directory. Otherwise, you 
must specify a hardcoded path. Locations you set in Workbench are stored in the project file. 


Because location settings will be shared among subprojects and possibly other developers, you 
should try to avoid absolute paths. If you need to share a project file and other source files that 
are not under your project’s directory, set environment variables in Workbench. 


LL) For more information on team design considerations, see the Development Guide. 


Modifying project entries 


> To modify project entries: 


1. Choose Project>Project Settings. 
2. Open the project to modify. 
You can choose between the current project and any associated subprojects. 
3. On the General tab, view (and if necessary modify) the classes directory and the archive 
directory. 
NOTE You cannot entirely modify the project type, directory, and file name within 
Workbench. See “Renaming a project” on page 37. 
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4. 


Select the Contents tab. 


A project entry can be a file or a directory. As shown below, each project entry is defined 


by its source location and associated archive location. 


Project: ProverbStart bd | 


General Contents | Classpath/Dependencies | 


Source location | Archive location 


B-INF', WVEB-INFS 
|<Root of Archive» 
WEB-INF iclasses/ 
resources) WEB-INFiclasses/comiproverbi 
C4 rStreamleXtendvV... [VVEB-INF Jib/struts jar 
C:\Program Files\SilverStreameXtendVV... MWEB-INF/ 



























Add Entry... | Add Directory... Fe Delete | 






P ‘OK Cancel 





Help 





Setting 


Description or action 





Project 


The project to modify. 





Source location 








The source location of the selected entry. A full 
path is listed whenever the source of the entry is 
not relative to the project root directory. 


Any files you later add to the source directory will 
also get included in the project archive. 


You can also use relative paths or environment 
variables when locating shared project files or 
referring to files located outside the project’s 
directory structure. 


LL) For more information, see “Using 
environment variables” on page 30 and “Using 
relative paths” on page 31. 
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Setting Description or action 





Archive location The archive location of the contents of the selected 
entry. The archive location can be the same as or 
different from the source location. 


All archive locations are relative to the archive 
root directory. 


Any path you specify identifies the directory 
structure in the archive. For example, specifying 
src\com\proverb would include those files and 
directories in the archive with src\com\proverb as 
the directory structure in the archive. 


An asterisk (*) indicates that you want to include 
all files in the specified directory, but not any 
nested subdirectories. 














Add Entry Lets you add a file to the project. 

Add Directory Lets you add a directory (and optionally 
subdirectories) to the project. 

Edit Lets you edit the selected entry name or location. 

Delete Lets you remove the selected project entry. 

















LQ) For information on adding an entry or directory, see “Adding source files to a 
project” on page 18. For information on removing entries, see “Removing files, 
directories, and subprojects from projects” on page 35. 
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Select the project entry you want to modify by either double-clicking the entry or selecting 


the entry and clicking Edit. 


The Edit archive entry dialog that appears depends on whether you are modifying a file, 


directory, or subproject entry. 


e The following dialog appears if you selected a file. The settings on this dialog are the 
same as on the Add to Project dialog. For more information, see “Adding to projects” 


on page 18. 








File: Param Files \SilverStreamteXtendyVorkbenchidocs tutorial\TutorialFiles\jars'struts jar 


© Add the file to the root of the archive. 


@ Add the file to the archive at this location: JNEB-INF fibistruts jar 


OK Cancel Help | 





e The following dialog appears if you selected a directory. The settings on this dialog 
are the same as on the Add to Project dialog. For more information, see “Adding to 


projects” on page 18. 


ZZ Edit archive entry Eg 


File: Jsps 











|V Include subdirectories 


@ Add the files to the root of the archive. 


© Add the files to the archive at this location: | 
Advanced => | 


i YOK Cancel Help | Cancel Help 
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e The following dialog appears if you selected a subproject. The settings on this dialog 
are the same as on the Add to Project dialog. For more information, see “Adding 
subprojects to a project” on page 21. 

File: [:WorkbenchProjects\SandboxiSandbox.spt 


M In 





(@ Add the generated archive of the subproject to the parent archive. 
© Add the contents (individual files) of the subproject to the parent archive. 


@ Add the child archive to the root of the parent archive. 


© Add the child archive at this location: | 





OK Cancel Help 


6. Click OK after you have modified the entry. 


Removing files, directories, and subprojects from projects 


There are two ways to remove items from a project: using the Project Settings dialog or using 
the Remove From Project popup menu in the Project tab. Removing a project’s source files or 
directories from within Workbench does not delete them from your hard disk. Workbench just 
removes the entry (or rule) that refers to the files or directories. 


> To remove a file using the Project Settings dialog: 


1. Choose Project>Project Settings. 
2. Select the Contents tab. 
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Select the entry or entries you want to remove from your project. Press Shift+Click to 
select contiguous entries. Press Ctrl+Click to select noncontiguous entries. 


3% Project Settings Eg 








Project: ProverbStart X | 
General Contents | ClasspathiDependencies | 


Source location | Archive location 


WWEB-INFS 

|<Root of Archive> 

WEB-INF /classes/ 
IWEB-INFiclassesicomipraverbi 





Cancel Help 





Click Delete. 


Click OK to perform the deletion. Click Cancel to close the dialog without performing the 
deletion. 


If you clicked OK, Workbench removes the entry or entries so they are no longer referred 
to in the project. 


Using the Remove From Project popup menu 


You can also right-click the file or directory you want to remove in the Project tab of the 
Navigation Pane. Choosing Remove From Project removes the project entry from the Project 
Settings definition (shown above and also reflected in the SPF file) as follows: 


When you remove an explicit file (one that does not refer to any other files contained in 
any nested directories), Workbench simply removes the entry so that it is no longer 
referred to in the project. 


When you remove an individual file or a directory that was added to a project as part of 
nested subdirectories, Workbench prompts you to confirm that you want to remove the 
whole tree from the project. To exclude a file from a nested project directory, for example, 
you should either remove the directory from the project (and add it again later without the 
file) or delete the file from your hard drive. 


You can remove a subproject by selecting it in the top part of the Navigation Pane (one 
subproject at a time) 
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What Workbench lists for you is the directory trees that will be removed. For example, if you 
select to remove sre\a\b\c.java, Workbench will advise that this will cause the sre directory tree 
entry to be removed. If you confirm that this is OK, Workbench removes the entire tree from the 
project. 


Renaming a project 


In rare cases, you may need to rename a project (the name preceding .SPF). Although you 
typically never directly edit a project file, you must do so in this situation. 


> To rename a project: 


1. Using your operating system tool, rename the project file. 


2. (Optional) On the Contents tab of the Project Settings dialog, change the classes directory 
to match the revised project name. This ensures that the new project name will appear as a 
subdirectory of the build directory. 


3. (Optional) Update the project name in the deployed object and the URL element in the 
deployment plan. 


Steps 2 and 3 are necessary only if you want to keep all project names consistent. The project 
will build without them. 


Compiling, building, and archiving 


Workbench provides the tools you need to compile individual Java source files, build a 
complete project, and package the components in a J2EE-compatible archive for deployment to 
a J2EE server. This section describes the procedures for: 


e Setting up your Workbench environment 


e Using the commands 


Setting up your Workbench environment 


Setting up your Workbench environment for compiling and building includes: 


e Defining the Java compiler 


e Defining the project classpath 
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Defining the Java compiler 


By default, Workbench uses the Javac 1.3 compiler. You can use the Build tab of the Preferences 
dialog to specify a different compiler. You can also specify options that you want sent to the 
compiler each time a Java file is compiled. 


LL) For more information, see “Build preferences” on page 15. 


Defining the project classpath 


The project classpath defines where Workbench can find the components that your source code 


references. 


You can use environment variables when editing a project classpath. 


LL) For more information, see “Using environment variables” on page 30. 


Workbench constructs the project classpath using these values: 











Item Description 
Workbench By default, Workbench uses: 
defaults 





e The standard JDK default classpath (for all projects) 


e The SilverStream eXtend Workbench JAR file that provides the 
J2EE API packages that are needed for compiling J2EE projects. 
For J2EE 1.2 projects, the file is j2ee_api_1_2.jar; for J2EE 1.3 
projects, the file is j2ee_api_1_3 jar. 


If the J2EE API JAR file is accidentally removed from the 
classpath, you can find it in the compilelib directory of the 
Workbench install directory. 
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Item Description 





Project contents The Contents tab of the Project Settings dialog lists the components 
that you’ ve added to a project. Workbench adds these items to the 
project’s classpath in the order in which you added them to the 
project. 





Classpath If your project has build dependencies on classes (for example, a 
WAR that contains a servlet that references an EJB), JARs (such as a 
Struts JAR), or related project files (like an EJB JAR and an EJB- 
client JAR), you can list these build dependencies using the 
Classpath/Dependencies tab of the Project Settings dialog. 


You can resolve the build dependency by adding either the related 
project’s SPF file or its archive to the classpath. It is recommended 
that you put the project’s SPF file on the classpath because: 


e If you put the project file on the classpath, Workbench can 
determine when the related project has changed and if the related 
project needs to be rebuilt. This ensures that you always have the 
most recent archive. 


e If you put the archive on the classpath, Workbench cannot 
determine if the project has changed (which might result in the use 
of outdated files). 














Parent project classpaths If you have a project that contains subprojects, Workbench 
builds the components and constructs the parent project’s classpath as follows: 
1. Builds any referenced projects before it builds the parent project. 


The referenced projects are specified in the Contents tab or Classpath/Dependencies tab of 
the Project Settings dialog. 


2. Ifthe referenced projects build successfully, Workbench builds the parent project using the 
following: 


1. The parent project’s contents 
2. The parent project’s classpath 


3. The referenced project’s classpaths (which are constructed following the same 
rules—the contents, the classpath, and any referenced projects) 


Suppose you have an EAR project, and the EAR contains a WAR (a subproject), and the 


WAR contains a utility JAR. Workbench constructs the JAR’s classpath first, then the 
WAR’s classpath. 
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> To add to a project classpath: 


With the project open, choose Project>Project Settings. 
Select the Classpath/Dependencies tab and select a classpath entry. 


$= Project Settings x| 
Project: ProverbStart z] 


General | Contents Classpath/Dependencies | 


Classpath entries: 






S6SILVERSTREAM_XVVB_HOME% \compilelib\2ee_api_1_3 jar 
‘Program Files\SilverStream\extendVVorkbenchidocs'tutorial\TutorialFiles y | 


| 
w 
In addition to directories and JAR files, you can add other project files (SPF files) to this 


project's classpath. Before this project is built, any SPF files listed here will automatically 
be built, and their generated archives will be used in the classpath. 


Add Entry... | Add Directory... | Edit... | Delete | 








TOK Cancel Help 


Click Add Entry or Add Directory. 
A selection dialog displays. 


If adding files, click Browse and navigate to the appropriate directory and select one or 
more files (archives or project files) and click Open. You can press Ctrl+Click to add 
multiple noncontiguous files and Shift+Click to add multiple contiguous files. 


Instead of browsing to files in the dialog, you can also directly type one or more files to 
add to the project’s classpath. Enclose each entry in quotes and separate the entries with 
spaces. When typing, you can specify environment variables (see “Using environment 
variables” on page 30). 


If adding a directory, type the directory (specifying environment variables if desired) or 
click Browse and select the directory. 


Click OK. 

Repeat Steps 3 and 4 for any other required items. 
(Optional) To edit a single classpath entry: 

1. Select the entry. 

2. Click Edit and modify the entry in the dialog. 
3. Click OK. 
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8. When you have added, positioned, and edited all required classpath entries, click OK to 
close the Project Settings dialog. 


You can now build the open project. 


Using the commands 


You can use the items on the Workbench Project menu to compile individual Java files, build 
an entire project, or create a project archive—or you can right-click a file, project, or archive, 
in the Navigation Pane to run the popup menu items. The menu items are: 





Project menu item 


What it does 





Compile 


Compiles the currently open Java file. 


(Does not perform checking for interdependencies 
between the currently open file and other files in the 
project and its subprojects.) 


NOTE Compile is not available in the popup menu 
that appears when you right-click a project file 
in the Navigation Pane. 





Build 








1. Compiles all files in the currently open top-level 
project and any subprojects. Performs dependency 
checking on modified files to avoid unnecessary 
recompilations. 


2. Saves the project’s modified files if the Always 
save modified files before compiling preference 
setting is enabled. For more information, see 
“Setting preferences” on page 13. 


3. Writes the generated class files to the locations 
specified in the Project Settings dialog. 
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Project menu item What it does 





Rebuild All 1. Compiles all files in the currently open top-level 
project and any subprojects regardless of what has 


been modified. 


2. Saves the project’s modified files if the Always 
save modified files before compiling preference 
setting is enabled. For more information, see 
“Setting preferences” on page 13. 


3. Writes the generated class files to the locations 
specified in the Project Settings dialog. 





ee 


Build and Archive 


. Executes the functionality described under the 
Build command (recompiles files subject to 
dependency checking). 


2. Creates the archives defined by the top-level project 
and its subprojects. 








Rebuild All and Archive 1. Executes the functionality described under the 
Rebuild All command (recompiles all files in the 


project). 





2. Creates the archives defined by the top-level project 
and its subprojects. 








> To compile a Java file: 


With a Java file open, select Projects>Compile. 


Workbench compiles the Java file and writes the compile messages to the Build tab of the 


Output Pane. 


> To build a project: 


With a Workbench project open, select Projects> Build. 


Workbench writes any build messages to the Build tab of the Output Pane. 


> To create an archive: 


With a Workbench project open, select Projects>Build and Archive. 


Workbench writes any build or archive messages to the Build tab of the Output Pane. 
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Building from the command line 


Workbench provides a command-line tool (xwbbuild) that allows you to build projects outside 


of the Workbench IDE. 


> To build a project from the command line: 


1. Open a command window. 


2. Make current the Workbench bin directory (it contains xwbbuild). 


3. Issue the following command: 


xwbbuild projectFile operation 


where: 





Argument 


Description 





projectFile 


Path to the SilverStream project (.SPF) file for the project you 
want to build 





operation 








One of the following: 


¢ build—Builds and creates the archive(s) for the specified 
project (equivalent to selecting Project>Build and Archive) 


¢ rebuild—Rebuilds and creates the archive(s) for the 
specified project (equivalent to selecting Project>Rebuild 
All and Archive) 


e clean—Removes all files from the project’s build directory 
and deletes the archive(s) (no equivalent in the Workbench 
IDE) 








NOTE xwbbuild displays messages while it processes the project. 


For example, the following command builds and creates the archive for the myApp Workbench 
project (if changes had been made since the last time the project was built and archived): 


xwbbuild c:\WorkbenchProjects\myApp\myApp.spf build 


NOTE The Workbench IDE and xwbbuild use Apache Ant to do the build processing. For 
more information on using Ant, including additional command-line options you can 
provide with xwbbuild and how to use Ant to do your own customized processing, see 
“Using Ant” on page 44. 
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Validating archives 


You should validate your archive’s deployment descriptor before attempting to deploy the 
archive. Selecting Project> Validate Archive runs Sun’s Verifier class. 


Validation process When validating, Workbench: 


1. Builds and archives the project. 


2. Validates the deployment descriptor of the project archive against both the deployment 
descriptor DTD specified by the J2EE specification and the contents of the archive. 


3. Validates the deployment descriptors of any subproject or prebuilt archives specified in 
the top-level deployment descriptor. 


NOTE Any subproject that is not listed in the parent project’s deployment descriptor 
will not be verified. 


4. Writes any messages to the Validate tab of the Output Pane. 


Validation output Validate Archive writes information to: 


e The Validate tab of the Output Pane 

e The results.txt file (located in your system TEMP directory) 

In the Validate tab of the Output Pane, you can double-click the line containing the string 
result.txt to open the file in the Text Editor. The result.txt file displays: 

e The archive that was tested 


e The type of errors or warnings (if any) that were found 


To validate a project archive: 


1. With the project open, select Project> Validate Archive. 
Selecting this menu item builds the archive and (if successful) validates it. 
2. After the process runs, check the Validation tab of the Output Pane. 
3. If there are validation errors, double-click the following text in the Validate Pane: 


Look in file "C:\TEMP\Results.txt" for detailed results on test 
assertions. 





The results.txt file opens. 


When you are through noting and fixing the errors, you can try validating the archive again. 
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3 Archive Deployment 





To make your J2EE application available to users, you deploy the archive on a J2EE server. This 
chapter describes how to deploy J2EE archives using Workbench and includes the following 
topics: 


Workbench-supported J2EE servers 

Workbench deployment types 

Using Workbench to deploy J2EE archives 

What Workbench does when you deploy a project 
Deploying Web Services 

Undeploying archives 


Workbench-supported J2EE servers 


Workbench provides built-in support for deploying archives to the following J2EE servers: 








Server Server archive support 
SilverStream Allows you to directly deploy application clients, EARs, EJB JARs, 
eXtend RARs, and WARs. 


Application Server 





BEA WebLogic Allows you to directly deploy application clients, EARs, EJB JARs, 
RARs, and WARs. 





IBM WebSphere Allows you to directly deploy EARs. 


Workbench allows you to develop any archive type. At deployment, 
Workbench repackages your archive as an EAR. 


Workbench supports local deployment to a Standard server only. 








Oracle9iAS Allows you to directly deploy EARs. 


Workbench allows you to develop any archive type. At deployment, 
Workbench repackages your archive as an EAR. 


You must wrap application clients in an EAR manually. 
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Server Server archive support 





SUN Reference Allows you to directly deploy EARs. 





= You must repackage other archive types in an EAR before deploying 
them. 
Jakarta Tomcat Allows you to directly deploy WARs. 














See the Release Notes for the latest information on the supported server versions. 


Workbench deployment types 
You can deploy the Workbench-produced archives using: 


e Workbench rapid deployment 
e Workbench production deployment 
e —Non-Workbench tools 


Workbench rapid deployment 


When developing, testing, and refining your application, you want fast turnaround—you want 
to make a change to your application and immediately see the result without having to redeploy 
the application. Workbench lets you do this using rapid deployment. You specify rapid 
deployment by simply checking a checkbox in Workbench’s Deployment Settings dialog 
(described in “Creating deployment settings” on page 8). When you deploy the application, 
Workbench uses the target server’s native file system deployment facilities. 


Rapid deployment is most useful for changes to Web applications that involve JSP pages, 
HTML pages, images, JARs in the WEB-INF\lib, or classes in the WEB-INF'\classes 
directories. If you make changes to other application components (like a WAR tag library or a 
deployment descriptor) Workbench automatically performs a full deployment. 


LL) For more information about setting up a rapid deployment environment, see “Creating 
deployment settings” on page 8. For more information about the target server’s native file 
system deployment, see “What Workbench does when you deploy a project” on page 14. 
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The following table lists the J2EE servers that allow you to use the Workbench rapid deploy 
feature and the kind of archives that you can rapid deploy with each: 





















































Server EAR WAR EJB CAR RAR 
SilverStream eXtend Application Server No No Yes No No 
(3.7.2) 

SilverStream eXtend Application Server Yes Yes Yes No No 
(3.7.x, starting with 3.7.3) 

SilverStream eXtend Application Server Yes Yes No No No 
(4.0 and higher) 

BEA WebLogic Yes Yes Yes No No 
IBM WebSphere Yes Yes Yes No No 
Jakarta Tomcat No Yes No No No 
Oracle9iAS Yes Yes Yes No No 
Sun Reference Implementation No Yes No No No 








Workbench production deployment 


When you’ve completely tested your application and are ready to put it into production, you can 
deploy the application to the server by unchecking the rapid deploy checkbox in the deployment 
settings for the target server. Workbench uses the target server’s native deployment tools to 
deploy the application in the appropriate deployment directory. 


Non-Workbench tools 


Alternatively, you can take your Workbench-generated archives and deploy them outside 
Workbench with the deployment facilities provided by your J2EE server. Because the archives 
Workbench generates are standard, you can deploy them to any standard J2EE server. 





Workbench deployment types 3 


3 Archive Deployment 





Using Workbench to deploy J2EE archives 


To deploy a J2EE archive using Workbench, the archive must: 


Be properly structured according to the J2EE specification (see “Archive contents” on 
page 5) 

Reside in a SilverStream eXtend Workbench project (see Chapter 2, “Projects and 
Archives”) 


Before Workbench can perform the deployment, you must supply: 


A server profile (see “Server profile” on page 24) 
Server-specific deployment information (see “Server deployment information” on page 7) 


Deployment settings (see “Creating deployment settings” on page 8) 


Before Workbench can perform the deployment, Workbench must have: 


Access to the target server 
Permission to write to the server’s deployment area 


Permission to write temporary files when deploying to a SilverStream server: When 
deploying to a SilverStream server, Workbench invokes SilverCmd, which generates 
temporary files on disk. These files are created in the server’s installation directory, unless 
you have defined a HOME environment variable. If you have a HOME variable, the 
temporary files are created in 7 HOME%\.silverstream. So if you have a HOME 
environment variable defined, it must point to a reachable and writeable location. 
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Archive contents 


Sun’s J2EE specifications define how different JZ2EE archives must be packaged for 
deployment. Before you try to deploy, make sure that your archive meets these requirements. 
The following table briefly lists the requirements. For more detailed information, see the J2EE 
Blueprints at: http://java.sun.com/j2ee/docs.html. 





J2EE 
module 


Standard archive requirements 





Application 
client 


A JAR file containing: 
e The Java classes that implement the application client 


e A deployment descriptor called application-client.xml located in the 
JAR’s /META-INF directory 


e A manifest file with a Main-Class entry 


LL) For more information, see J2EE Deployment Descriptors DTDs in 
the online Reference. 





EAR 


An EAR file containing: 


e The component archive files (such as EJB JAR files, WAR files, and 
application client JAR files); each of these components must include its 
own deployment descriptor 


e A deployment descriptor for the EAR called application.xml located in 
the EAR’s /META-INF directory 


LI For more information, see J2EE Deployment Descriptor DTDs in the 
online Reference. 





EJB JAR 








A JAR file containing: 


e The bean implementation class, the remote and home interfaces, the 
primary key classes (if necessary), and any other utility classes 


e A deployment descriptor called ejb-jar.xml located in the JAR’s /META- 
INF directory 


LL) For more information, see J2EE Deployment Descriptor DTDs in the 
online Reference. 
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J2EE 
module Standard archive requirements 
RAR A RAR file containing: 
e The classes needed to implement the resource adapter 
e A deployment descriptor called ra.xml located in the JAR’s /META-INF 
directory 
WAR A WAR file containing: 


e JSP source files, Web Services, servlet classes, other supporting Java 
components, HTML documents, images, and other files required by the 
application 


e A deployment descriptor called web.xml located in the WAR’s /WEB- 
INF directory 


e Helper classes in the WAR’s /WEB-INF/classes directory 
e Helper libraries in the WAR’s /WEB-INF/lib directory 


LL) For more information, see J2EE Deployment Descriptor DTDs in the 
online Reference. 
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Server deployment information 


Each J2EE server needs runtime information, and each has its own format for this information. 
The following table lists the deployment documents needed by each Workbench-supported 















































server: 
J2EE server Archive Server deployment information 
SilverStream Application | Each type of archive uses an XML-based document 
eXtend client called a deployment plan. The deployment plan can have 
Application (CAR) any file name and can reside in any location outside the 
Server archive file. SilverStream defines a DTD for each archive 
EAR t 
ype. 
EJB LL) For more information, see SilverStream 
RAR Deployment Plan DTDs in the online Reference. 
You use Workbench’s Deployment Plan Editor to create 
WAR and populate the deployment plan. 
LL) For more information, see “Deployment Plan 
Editor” on page 301. 
BEA WebLogic | Application | Each type of archive (except EAR) requires a special 
client XML-based document. The EAR does not require a 
specific deployment document, but each individual 
EAR module included in the EAR must have the appropriate 
EJB WebLogic deployment document. 
C For more information, see your WebLogic 
RAR : 
documentation. 
WAR 
IBM Application | Each type of archive uses one or more deployment 
WebSphere client documents. 
EAR (4) For more information, see your WebSphere 
documentation. 
EJB JAR 
WAR 
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J2EE server Archive Server deployment information 
Oracle9iAS Application | Each type of archive requires a special XML-based 
client document. 
EAR CJ For more information, see your Oracle9i1AS 
documentation. 
EJB JAR 
WAR 
SUN Reference | EAR META-INP/sun-j2ee-ri.xml 
Implementation 
P (J For more information, see J2EE RI Runtime 
Deployment Descriptor DTD in the online Reference. 
Jakarta Tomcat | WAR No specific file is needed. 








Creating deployment settings 


Before you can deploy a Workbench project, you need to define the project’s deployment 
settings. They provide information about the server on which you plan to deploy the project. 


> To create deployment settings: 


1. Choose Project>Deployment Settings. 


NOTE Ifyou are deploying to a SilverStream server and the project’s current 
deployment plan is not associated with a server profile, you will be told that you 
need to specify a server profile before the Deployment Settings dialog can be 
displayed. Do so in the Edit Server Profiles dialog, then continue specifying the 


deployment settings. 
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2. Inthe Server Profiles tab, specify the following information: 














Option What to do 

Profile name | Select a server profile from the list or click Add to create a new 
profile. 
LL) For more information on server profiles, see “Server profile” 
on page 24. 

Save this Select this option to make the current server profile the default profile 

profile as in new projects. 

default 

User name If you have a secure server, fill in the User name and Password text 


and Password | boxes with an authorized user name and password for the server. 














3. Select the Deployment Info tab. 
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4. Specify the following options for servers that support rapid deployment: 














Option What to do 
Enable Rapid | Check this box when you want to deploy the archive using the rapid 
Deployment deployment feature. Uncheck it when you want to do a production 


deploy. 


What happens When this checkbox is checked, Workbench writes 
files to the rapid deployment directory specified in the server profile. 


NOTE If you have not set a rapid deployment directory in the server 
profile, you are prompted for one. This directory is not the 
same as the location for the server’s deployment tools. It is a 
location on disk where you want the server to write the 
deployment files. Many servers require a specific directory; 
see “Server profile” on page 24 for the list. 


Further action Workbench manages updates to the deployment 
area on subsequent rapid deploys. You do not have to do any manual 
procedure that you have to when directly using the server’s rapid 
deployment. 


When to use Use rapid deployment during the 
development/test/refinement stage of your application development 
cycle. Do not use it when you deploy your application to a 
production environment. 


LL) For more information on rapid deployment and how each 
server supports this feature and any special requirements, see “What 
Workbench does when you deploy a project” on page 14. 
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5. Specify server-specific information: 


For SilverStream eXtend Application Servers, specify the following: 























Option What to do 
SilverStream | Specify the file name and disk location of the SilverStream 
Deployment deployment plan 
Plan 
Overwrite Check this box when you want the current deployment to overwrite 
existing any previously deployed objects of the same type and name 
deployment If you deselect this box and objects of the same name and type 
already exist on the server, the deployment will fail 
Verbosity Specify the level of informational messages to display 
Values range from 0 (for no messages) to 5 (for the most messages) 
Ignore Applies only to WARs and to EARs containing WARs 
compre Check this box when you want the deployment to ignore any errors 
errors ce ; ; 
when compiling and to deploy only those items that build 
successfully 
If this box is not checked and a compile error occurs, deployment 
fails 
SilverCmd (Optional) Specify command-line arguments for the deployment 
Flags command 
LL) For more information on the deployment commands that are 
executed, see the “What Workbench does when you deploy a project” 
on page 14 
If you specify multiple arguments, use spaces as the delimiters. If you 
want to pass VM arguments, then you must precede them with +. For 
example: 
+Xmx256 
All of the values entered here are appended to the end of the 
deployment command that Workbench constructs 














Using Workbench to deploy J2EE archives 


11 


3 Archive Deployment 





For BEA WebLogic servers, specify: 





Option 


What to do 





WebLogic Application Name 


Specify the deployment name for your application. 
If this is a rapid deploy, this is the directory name 
under the deployment directory. 


Workbench defaults to the project name. 





Generate Targets 


Choose this button to automatically create a list of 
components to deploy to the target servers specified 
in the server profile. The list is displayed in the 
Components and Targets text box. 





Components and Targets 








Do one of the following: 


e Accept the values created when the Generate 
Targets button is selected. 


e Edit the values created when the Generate Targets 
button is chosen. 


e Manually type the name of the components and 
their target servers. Use a colon after the 
component name, a comma between targets, and 
a semicolon between component:target pairs— 
for example: 


componenta:target, target ;componentx: tar 
get,target 
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Option 


What to do 





Deployment options Choose one of these options: 


e deploy—deploys the application. Use this option 
when deploying the application for the first time. 
If rapid deploy is checked, this option performs a 
rapid deploy; otherwise, it performs a production 
deploy. 


e update—updates a deployed application. Use 
this option for all redeployments, updates to an 
already deployed archive, or to enable a disabled 
application. 


e undeploy—disables the application. 


e list—provides a list of all deployed applications 
on the server specified by the current project’s 
server profile. 





debug 





Check this option when you want to see the debug 
information produced by the WebLogic deploy tool. 











For IBM WebSphere servers, specify: 





Option 


What to do 





Node Name 


Specify the name of the Standard server node to install to 





Precompile 
JSP 








Click the checkbox (true) if you want to precompile any JSP pages 
before deploying to the server 








For Oracle9iAS servers, specify: 





Option 


What to do 





Deployment 
Name 








Specify the application deployment name 
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Target Path Specify the path on the server to deploy to 





Website Specify the name of the OC4J web-site.xml file containing the name 
Name of the Web site to bind this application to 














Select OK to store the deployment settings with the project file. 
OR 
Select Deploy to save the deployment settings with the project file and deploy the archive. 


If you select Deploy and you specified a user name, you are prompted for the password 
before deployment can continue. 


> To deploy a Workbench project: 


1. 


Open the Workbench project. 


Any archive that you want to deploy must be defined in a Workbench project. If you 
created the archive using another IDE, you must create a Workbench project for it before 
you can deploy it. 


Make sure you have the server-specific deployment information in the appropriate format 
and location for your target server. 


LL) For more information, see “Server deployment information” on page 7. 
Define the deployment settings for the project. 

LI For more information, see “Creating deployment settings” on page 8. 
Select Project>Deploy Archive. 


The first time you select Project>Deploy Archive, you must choose from a list of server 
profiles. Use New on the Server Profile dialog to create a server profile if you don’t 
already have one. 


What Workbench does when you deploy a project 


When you deploy a project, Workbench uses the deployment settings to determine the J2EE 
server. Then: 


1. 


Workbench compiles the Java files and creates an archive. (JSP files are compiled during 
deployment or when their URLs are invoked from a browser.) 
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2. When the compilation is successful, Workbench calls the appropriate deploy command for 
the target server. 


The following table lists the deploy command that is called for each server: 











Server Archive Deploy command description 

SilverStream | CAR Standard/Production deploy: SilverCmd DeployCAR 
eXtend í 

Application Rapid deploy: Not supported for CARs 

Server EAR Standard/Production deploy: SilverCmd DeployEAR 


Rapid deploy: Rapid deployment is supported for 
EARs for SilverStream eXtend Application Server 
Version 3.7.3 and later. It supports the rapid deployment 
of WARs in the EAR. It works like this: 


e When a JSP page, an HTML page, a CLASS file, or a 
JAR file in a WAR within the EAR changes, 
Workbench invokes the server’s JSP/FS deployment. 


e When other files in the EAR are changed (such as the 
EAR deployment plan, EAR deployment descriptor, 
EJB archive, client archive, WAR deployment plan, 
or WAR tag library), Workbench invokes the 
standard/production deployment. 


e Workbench manages updates to the deployment area 
on subsequent rapid deploys (so you do not need to 
do any manual procedure that you might have to 
when directly using the server’s rapid deployment). 





EJB JAR Standard/Production deploy: SilverCmd DeployEJB 


Rapid deploy: SilverCmd QuickDeployEJB (3.7.x 
only) 


e You must use the standard deploy process the first 
time you deploy. You can use the rapid deploy feature 
on subsequent deployments. 
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Server Archive Deploy command description 





WAR Standard/Production deploy: SilverCmd DeployWAR 
Rapid deploy for Version 3.7.3 (and later): JSP/FS 
During the JSP/FS process: 


e Workbench expands the WAR file in the directory 
SilverStreamInstallDir/webapps/DBname/URL 


where SilverStreamlInstallDir is the directory 
containing the SilverStream eXtend Application 
Server installation, DBname is the name of the 
database containing the application deployed to the 
file system, and URL is the URL specified in the 
deployment plan for the application (if you have 
specified more than one, the first one is used). 


e Workbench manages updates to the deployment area 
on subsequent rapid deploys (so you do not need to 
do anything manually that you might have to when 
directly using the server’s rapid deployment such as 
creating the RELOAD file). 


e Workbench updates the <deployToFileSystem> 
attribute automatically when you specify a rapid 
deploy. 
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Server Archive Deploy command description 
BEA All Standard/Production deploy: weblogic.deploy 
Webleric see Rapid deploy: Workbench uses WebLogic’s Dynamic 





Deployment feature to provide rapid deployment of 
EARs, EJBs, and WARs. You’ll need to enable 
WebLogic Auto-Deployment through the WebLogic 
Management console before Workbench will be able to 
perform a rapid deploy. For more information on setting 
Auto-Deployment, see your WebLogic documentation. 


e During a rapid deploy, Workbench copies the 
modified files to the user-specified deployment 
directory and touches the REDEPLOY file. 


e Ifyou want to do a standard deployment after a rapid 
deployment, delete the rapid deployment directory 
and then do the standard deployment. If you do not 
delete the rapid deployment directory, your changes 
will not be reflected. 
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Server 


Archive 


Deploy command description 





IBM 
WebSphere 


All 
supported 
archives 


Standard/Production deploy: seappinstall 


Rapid deploy: Workbench copies the modified files to 
the user-specified deployment directory. 


e You must use the standard deploy process the first 
time you deploy. You can use the rapid deploy feature 
on subsequent deployments. 


e Ifthe changes to an EAR include changes to the WAR 
deployment descriptor, TLD files, or files located in 
WEB-INF\lib or WEB-INF\classes in the WAR, 
you'll need to restart the server to see the changes. 


e If you remove a file from any of the archives within 
the EAR, you’ll need to: 


1. Stop the server 
2. Remove the class from the following: 


3. WebSphereinstalldir\AppServer\temp\machine_name 
\Default_Server\applicationname 


4. Restart the server 








Oracle9i1AS 





All 
supported 
archives 





Standard/Production deploy: admin.jar 


Rapid deploy: Workbench copies the modified files to 
the user-specified deployment directory. 


e You must use the standard deploy process the first 
time you deploy. You can use the rapid deploy feature 
on subsequent deployments. 


e For rapid deployment of EARs, the deployment 
directory specified must be the server’s \applications 
directory. 


e If you are updating an EAR and the updates include 
changes to the WAR deployment descriptor, TLD 
files, or files located in WEB-INF\lib or WEB- 
INF\classes in the WAR, you’ll need to restart the 
server to see the changes. 
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Server 


Archive 


Deploy command description 





SUN RI 


EAR 


Standard/Production deploy: deploytool 


Rapid deploy: copy 


You must restart the server after a standard deploy 


Explodes the archive then copies the contents to a 
deployment directory specified by the user 


If the rapid deploy directory does not exist, 
Workbench creates it 


On subsequent rapid deploys, only the changed files 
are copied to the deployment directory 


You must restart the server after a rapid deploy 





Jakarta 
Tomcat 








WAR 





Standard/Production deploy: copy 


Rapid deploy: copy 


Copies the archive to the server’s \webapps directory 


You must restart the server after a standard deploy 


Explodes the archive then copies the contents to a 
deployment directory specified by the user 


On subsequent rapid deploys, only the changed files 
are copied to the deployment directory 


You do not need to restart the server after a rapid 
deploy 








3. The target server’s deployment command creates the appropriate deployment objects on 


the target server. 


4. Workbench displays a message stating the status (success or failure) or any warning or 
error messages in the Deploy tab of the Output Pane. 
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Deploying Web Services 


When you create a Web Service in Workbench by using the Web Service Wizard or by using 
jBroker Web directly, a servlet is generated to handle access to that Web Service (from HTTP 
SOAP requests). As a result, a WAR is required to package your Web Services (one or more per 
WAR) for deployment to a J2EE server where they will run. 


You deploy that WAR in the usual way (as described earlier in this chapter). In addition, you 
must make sure it has runtime access to the following archives required by jBroker Web: 
e  jbroker-web.jar, which contains the jBroker Web API classes 


e jaxrpc-api.jar and saaj-api.jar, which contain the Java API classes for XML-based RPC 
and SOAP processing 


e  xerces.jar or another XML parser 


e If the WAR uses SOAP message handlers (an advanced JAX-RPC feature), it will also 
require the following archives: activation.jar, commons-logging.jar, dom4j.jar, jaxp- 
api.jar, and saaj-ri.jar 

How you set up this access depends on the type of J2EE server you use: 

If you deploy to one of the following servers, you must add the required JARs to the server’s 

classpath. (Consult your server documentation to learn about adding to the classpath.) 

e BEA WebLogic 

e IBM WebSphere 

e Jakarta Tomcat 

e  Oracle9i 

If you deploy to the SilverStream eXtend Application Server, there’s no need to add the 

required JARs to the server’s classpath as long as you include them in the WEB-INF/lib 

directory of your WAR. If you don’t include the required JARs in the WAR, you must add them 
to the server’s AGCLASSPATH environment variable or specify them with the classpathJars 


deployment plan element. (For more information about AGCLASSPATH and classpathJars, see 
the SilverStream eXtend Application Server Core Help.) 


You can obtain the required JARs by copying them from the Workbench compilelib directory. 
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Undeploying archives 


Depending on the deployment server, you can disable or delete deployed archives from the 
server from within Workbench. 


Workbench doesn’t directly perform the undeployment; it calls server facilities to do the work. 
So, for example, if a server supports deletion but not disabling of archives, then you can delete 
but not disable archives from Workbench. 


Typically, disabling leaves the files on the server but makes them unavailable, and deleting 
physically removes the files from the server. However, since Workbench simply executes the 
server’s undeployment facility, exactly what happens depends on the server. For example, 
undeploying an application that had been deployed with Rapid deployment does not necessarily 
delete or rename the deployment directory; the server might just delete the references to that 
application from its metadata. See your server documentation for information about exactly 
what happens when you undeploy an archive. 


Here is the undeployment support for the servers supported by Workbench: 




















Server Disable? Delete? Notes 

SilverStream 3.x No Yes 

SilverStream 4.x No Yes 

BEA WebLogic Yes Yes 

IBM WebSphere Yes Yes 

Oracle9i AS No No Oracle9iAS Version 1 does not have 


an undeploy feature. To remove an 
application, you must manually 
delete the directories and archives 
and remove the references from the 
configuration files. 








Jakarta Tomcat No No Tomcat does not have an undeploy 
feature. 

Sun Reference No Yes 

Implementation 
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> To undeploy an archive: 


1. 


With the project open, select Project>Undeploy Archive. 


NOTE The menu item is disabled if the deployment server does not provide an undeploy 
feature. 


The dialog that displays depends on the type of server specified in your project’s 
Deployment settings. 


e Ifyour deployment server supports both disabling and deleting archives, you are asked 
which action you want to perform 


e If your deployment server supports only disabling archives, you are asked to confirm 
the disabling action 


e If your deployment server supports only deleting archives, you are asked to confirm 
the deletion 


Respond to the dialog. 


The archive is either disabled or deleted. You can see the commands that Workbench 
issues in the Deploy tab of the Output Pane. 
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4 Component Wizards 





To speed project development, use Workbench wizards when creating Java components: 
e EJB Wizard 

e JSP Wizard 

e Servlet Wizard 

e Java Class Wizard 

e JavaBean Wizard 


e Tag Handler Wizard 


You access the wizards by choosing File>New from the menu. 


EJB Wizard 


Use the EJB Wizard to create EJB1.1 entity and session beans or EJB2.0 entity, session, and 
message beans. The following sections describe: 


e About the EJB Wizard 
e Starting the EJB Wizard 
e Panel sequence 


e Panel reference 


About the EJB Wizard 


The EJB Wizard can speed your EJB development effort by providing: 


e A skeleton of the bean implementation class 
e The home, remote, local, and localhome interfaces (as needed) 
e A primary key class (as needed) 


Once you have created the EJB using the EJB Wizard, you can modify it in the Java Editor by 
opening its Java source files in the Project tab of Workbench. 
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Starting the EJB Wizard 


> To start the EJB Wizard: 
1. Click File> New. 


2. On the J2EE tab, choose EJB and click OK. (Alternatively, you can double-click EJB.) 


3. The steps that you follow depend on the type of bean you want to generate, see “Panel 


sequence” on page 2 for more information. 


Panel sequence 


This section lists the panels you need to complete in the EJB Wizard, depending on the type of 
bean you want to create You can click the link to get more information about how to complete 


the panel. 





If you want to create 


You step through these panels 





A stateful or stateless session bean 








1. Specifying the EJB type 
2. Specifying the EJB JAR configuration 


3. Specifying the project, package, and 
directory 


4. Specifying the EJB source 
e Specifying the source class or interface 


5. Specifying the EJB class and interface 
names 


6. Specifying methods 


7. Specifying additional classes or packages 
to import 


8. Completing the EJB 
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If you want to create 


You step through these panels 








A message-driven bean 





1. 
2. 
3. 


Specifying the EJB type 
Specifying the EJB JAR configuration 


Specifying the project, package, and 
directory 


. Specifying the EJB source 


e Specifying the source class or interface 


. Specifying the EJB class and interface 


names 


. Specifying methods 


. Specifying additional classes or packages 


to import 


. Completing the EJB 








EJB Wizard 
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If you want to create 


You step through these panels 





A BMP entity bean 








1. Specifying the EJB type 
2. Specifying the EJB JAR configuration 


3. Specifying the project, package, and 
directory 


4. Specifying the EJB source 
e Specifying the source class or interface 
or 


e Specifying the source database and 
Selecting a database table 


5. Specifying the EJB class and interface 
names 


6. Specifying persistent (data) fields 
7. Specifying primary key fields 


8. Specifying fields that require get/set 
methods 


9. Specifying create() methods 
10. Specifying find() methods 


11. Specifying additional classes or 
packages to import 


12. Specifying resource references 


13. Completing the EJB 
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If you want to create 


You step through these panels 








A 1.x CMP entity bean 





1. Specifying the EJB type 
2. Specifying the EJB JAR configuration 


3. Specifying the project, package, and 
directory 


4. Specifying the EJB source 
e Specifying the source class or interface 
or 


e Specifying the source database and 
Selecting a database table 


5. Specifying the EJB class and interface 
names 


6. Specifying persistent (data) fields 
7. Specifying primary key fields 


8. Specifying fields that require get/set 
methods 


9. Specifying create() methods 
10. Specifying find() methods 


11. Specifying additional classes or 
packages to import 


12. Completing the EJB 
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If you want to create 


You step through these panels 








A 2.x CMP entity bean 





1. 
2 
3. 


9. 


Specifying the EJB type 
Specifying the EJB JAR configuration 


Specifying the project, package, and 
directory 


. Specifying the EJB source 


e Specifying the source class or interface 
or 


e Specifying the source database and 
Selecting a database table 


. Specifying the EJB class and interface 


names 


. Specifying persistent (data) fields 
. Specifying primary key fields 
. Specifying fields that require get/set 


methods 


Specifying relationships 


10. Specifying create() methods 


11. Specifying find() methods 


12. Specifying additional classes or 


packages to import 


13. Completing the EJB 








Panel reference 


This section describes the options on each panel of the EJB Wizard. The panels are: 


Specifying the EJB type 

Specifying the EJB JAR configuration 
Specifying the project, package, and directory 
Specifying the EJB source 


Specifying the source database 
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e Selecting a database table 

e Specifying the source class or interface 

e Specifying the EJB class and interface names 
e Specifying methods 

e Specifying persistent (data) fields 

e Specifying primary key fields 

e Specifying fields that require get/set methods 
e Specifying create() methods 

e Specifying relationships 

e Specifying findQ methods 

e Specifying additional classes or packages to import 
e Specifying resource references 

e Completing the EJB 


Specifying the EJB type 
This panel lets you specify the type of EJB you want to create. 
Select the type of EJB that you want to create. Entity EJBs 


represent persistent data, session EJBs contain business 
logic, and message-driven EJBs handle messages. 
















Entity EJB, container-managed persistence version 1.x 


Entity EJB, container-managed persistence version 2.x 
Entity EJB, bean-managed persistence 

Session EJB, stateless 

Session EJB, stateful 

Message-driven EJB 


xte Cancel 
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> To complete this panel: 
1. Specify the EJB type: 

















Option What to do 
Entity EJB, container- Select this option when you want the EJB Wizard to 
managed persistence create an entity bean that uses container-managed 
version 1.x persistence (CMP) defined by the EJB1.1 specification 
Entity EJB, container- Select this option when you want the EJB Wizard to 
managed persistence create an entity bean that uses container-managed 
version 2.x persistence (CMP) defined by the EJB2.0 specification 
Entity EJB, bean-managed | Select this option when you want the EJB Wizard to 
persistence create an entity bean that uses bean-managed persistence 
(BMP) 
Session EJB, stateless Select this option when you want the EJB Wizard to 


create a stateless session bean 


A stateless session bean is released to the instance pool 
after each method call completes, so it is not guaranteed 
that a client will have the same instance on subsequent 
method calls 





Session EJB, stateful Select this option when you want the EJB Wizard to 
create a stateful session bean 


A stateful session bean is bound to the client session that 
creates it, so it can be used to maintain values associated 
with that client session 





Message-driven EJB Select this option when you want the EJB Wizard to 
create a message-driven bean 














2. Click Next to continue. 


Return to “Panel sequence” on page 2. 
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Specifying the EJB JAR configuration 


This panel lets you specify whether the wizard should create one EJB JAR or an EJB JAR and 
an EJB-client JAR. 


ZZ EJB Wizard Eg 









J2EE recommends creating 2 separate JARs for an EJB -- 
the "EJB-client JAR" to contain the classes needed to use the 


EJB, and the "EJB JAR" for the EJB's implementation 
class(és). 


@ Create classes in separate EJB-client & EJB JARs 
© Create classes in a single EJB JAR. 


Gancel 
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> To complete this panel: 


1. Specify the EJB JAR configuration: 








Option What to do 
Create separate EJB- Select this option if you want the wizard to use these two 
client & EJB JARs JARs: 


e EJB JAR—Contains the bean implementation classes, 
any utility classes that are private to the implementation, 
and a deployment descriptor in the META-INF 
directory. 


¢ EJB-client JAR—Contains the EJB home and remote 
interfaces, a primary key class, and any utility classes 
that a client might require to use the EJB. The EJB- 
client JAR is a plain archive file; it does not contain a 
deployment descriptor. If you have EJBs that are used 
by other EJBs in the EJB JAR (like helper EJBs) but are 
not used by clients, then do not put the home and remote 
interfaces of the helper EJBs in the EJB-client JAR. 





Create a single JAR for | Select this option if you want the wizard to use a single 
all EJB classes EJB JAR that will contain all of the EJB classes and 
interfaces. 











2. Click Next to continue. 


Return to “Panel sequence” on page 2. 


How EJB JARs and EJB-client JARs are related in a project An EJB-client JAR 
project is a peer to its EJB JAR project—tt is not a subproject of the EJB JAR project. The EJB 
JAR and EJB-client JAR are linked in the following ways: 


e EJB JAR project classpath includes EJB-client JAR project 


e EJB JAR has a manifest file that includes a Class-Path entry for the EJB-client JAR 
archive 


e The EJB JAR’s deployment descriptor contains an <ejb-client-jar> element containing the 
name of the EJB-client JAR archive 


If you create an EJB JAR as a subproject, its EJB-client JAR will also be made a subproject of 
the same parent project. The EJB-client JAR will have the same project location, same archive 
location, same subproject status, and same inclusion in its parent archive as the EJB JAR. 
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Specifying the project, package, and directory 


This panel is used to specify details about the project location (project, directory, package) 
where the wizard is to store the EJB files it generates. 


If you chose to use both an EJB JAR and an EJB-client JAR, you are prompted to provide 


the project/package/directory information for the EJB-client JAR on a panel similar to this one. 


Specify the project, package, and directory for the new EJB 
JAR's implementation class. 


( Add to open EJB JAR project: [DocExample z] Create project... | 


© No project -- just write files to the disk. 



















Base directory: F:\Varies'DocExampleisre z] Browse... | 
Package: | 


File directory: C:\4ries'\DocExampleisrc\ 
NOTE: The entire contents of this directory will be included in the archive. 


@ Add the files to the root of the archive. 


@ Add the files to the archive with this prefi | 


The files will be added to this location in the archive: 

















lei Cancel Help 
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> To complete this panel: 


1. On the top portion of this panel of the EJB Wizard, specify one of the following three 


project association options: 





Option 


What to do 





Add to open EJB JAR project 


If you currently have one or more EJB projects open 
in Workbench, you can add the EJB to one of those 
projects by selecting it from the dropdown list. If the 
project that you want to associate the EJB with is not 
currently open, you must open the target project 
before starting up the EJB wizard. 


If the EJB project is defined as an EJB1.1 project, 
then you cannot add EJBs that use EJB2.0 features— 
and the wizard prevents you from doing so. 





Create project 


Click Create project to start the New Project 
Wizard. 


When you create a new EJB project, you are 
prompted to specify whether it is an EJB1.1 or 
EJB2.0 project. You can add EJB1.1 beans to an 
EJB2.0 project, but not vice versa. 


LL) For details, see “Creating projects and 
subprojects” on page 56. 





No project -- just write files to 
the disk 








If you do not want to associate the EJB with any 
Workbench project, you can still use the wizard to 
create the class in a nonproject directory on the file 
system. 
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2. On the bottom portion of this panel of the EJB Wizard, specify the following: 





Option What to do 





Base directory If you specified an EJB project, the default base directory is the 
project directory. Otherwise, this field is empty. (Click Browse to 
specify a file system location.) 





Package Specify the EJB’s package name. This is required in the 
Workbench environment. 





File directory The contents of Base directory and Package are combined to 
specify the location of the EJB source file, which is displayed 
under the File directory. 


This is the file system location where the wizard creates the bean 
source file and home and remote interfaces. 














3. Click Next to continue. 


Return to “Panel sequence” on page 2. 


Specifying the EJB source 


This panel is used to identify whether the EJB source that the wizard generates should be 
completely new, based on an existing source file, or (for entity beans) a database table. 
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You can specify an existing database table that defines the 
fields for the EJB, or an existing EJB class that defines fields 
and methods. Otherwise, choose "from scratch" to enter this 
information manually. 


@ Create EJB from scratch 
© Create EJB from a database table 


© Create EJB from an existing Java class or interface 





> To complete this panel: 


1. Choose one of the following options: 











Option What to do 
Create EJB from scratch Select this option if you want to create a new EJB 
Create EJB from database Select this option to create an entity bean whose fields 


are based on the fields in a specific database table 





Create EJB from an existing | Select this option to use the properties of an existing 
Java class or interface EJB class or interface as the starting point for your EJB 











2. Click Next to continue. 


Return to “Panel sequence” on page 2. 


Specifying the source database 


This panel is used to specify the information that the wizard needs to connect to a database. 
Once connected to the database, it is able to get the list of database tables so that you can pick 
the database table on which the entity bean should be based. 
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$= EJB Wizard Eg 


Specify the database URL and JDBC driver for the database 
that you want to access. Include the username & password if 


they are required. See your system administrator for more 
details. 


Database [tasaSab + | 





Database username: | 


Database password: | 





<Back Next> Cancel Help 
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> To complete this panel: 








1. Specify: 
Option What to do 
Database Select a database profile from the dropdown list box. If the 


dropdown is not populated or if the existing profiles are 
unsuitable, you must create a database profile by clicking New 
or leaving the wizard and choosing Edit>Profiles and selecting 
the Databases tab. 


When you complete this panel (by clicking Next), Workbench 
creates a client connection to the database. This means that the 
database driver (specified in the database profile) must be 
available to Workbench. 


You can make the driver available in one of two ways: 


e Putting the database driver in the Workbench lib/ext 
directory, where it will be picked up automatically by 
Workbench. 


OR 


e Putting the location of the driver on Workbench’s classpath 
(not the project classpath—but the classpath used when you 
start Workbench.) 


L For more information on database profiles, see “Database 
profile” on page 27. 





Database username 
and Database 
password 








Type a user name and password that you can use to connect 
directly to the specified database. This user name and password 
combination must allow access to the database’s system tables 
so that Workbench can access the database’s metadata. 





2. Click Next to continue. 


Return to “Panel sequence” on page 2. 


Selecting a database table 


This panel presents a list of database tables. You can select the database table that you want to 
use as the basis for your entity bean. 
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32 EJB Wizard | x} 


Select the database table from which to create the EJB. 


Creator: [DBA te | 


Table: = AgAccessRights 
AgA&gents 
AgContents 
Aginto 
AgResources 
LEAGUE 
PLAYER 
TABLE_TYPE 
TEAM 
TEAM_PLAYER 














Gancel Help 


> To complete this panel: 


1. Specify the following two options: 

















Option What to do 

Catalog/Creator/ | Select the Catalog/Creator/Schema containing the database table 

Schema you want to use for the entity bean 

Table Select the database table that contains the fields you want to 
include in the entity bean 








2. 


Click Next to continue. 


Return to “Panel sequence” on page 2. 


Specifying the source class or interface 


This panel lets you choose an existing Java class or interface that the wizard should use as the 


basis for your EJB. 





EJB Wizard 
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Specify the compiled Java .class file from which to create the 
EJB. For This existing class should be an EJB remote 
interface or implementation class. 






Existing file: | Browse... | 








Cancel Help 





davies 
Jari = 


> To complete this panel: 








1. Specify: 
Option What to do 
Existing file Click Browse to locate the remote interface or EJB class that you 








implementation or remote interface 


want to use as the starting point for your EJB 


The file you specify can only be a class file for a bean 





2. Click Next to continue. 


Return to “Panel sequence” on page 2. 


Specifying the EJB class and interface names 


This panel lets you specify a name for the EJB classes and interfaces that the wizard generates. 
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How the wizard names EJBs The EJB Wizard generates names for the EJB’s 


implementation classes and interfaces based on a Base name that you supply in this wizard 


panel. It follows these rules when naming the EJB components: 





EJB component 


Naming conventions 





Bean class 


Prepends EB, SB, or MB and appends Bean to the base name 


For example, SBCalculatorBean 





Remote interface 


Prepends EB or SB to the base name 


For example, SBCalculator 





Home interface 


Prepends EB or SB and appends Home to the base name 


For example, SBCalculatorHome 





Local interface 


Prepends EB or SB and appends Local to the base name 





(EJB2.x only) For example, SBCalculatorLocal 

Local home Prepends EB or SB and appends LocalHome to the base name 
Ge For example, SBCalculatorLocalHome 

(EJB2.x only) 





Primary key classes 


(entity beans only) 








Prepends EB and appends PK to the base name 
For example, EBCustomerPK 
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Specify the names of the EJB classes & interfaces. 
Base name: | 
Logical EJB name: | 
Implementation class: | 


[E Create a primary key class 


Primary key cla | 
Please select the set of interfaces to be generated. 


@ Remote interfaces (© Local interfaces 


Remote interface: —__ ee 
Home interface: [eT 
Local interface [CY 
Local Home interface: [OO 





> To complete this panel: 





















© Remote and local interfaces 





Gancel Help 


1. On the top portion of this panel of the EJB Wizard, specify values for the following 








components: 
Option What to do 
Base name Specify a legal name for the EJB class and interfaces. This 


name is used to construct the names for the other EJB 
components 


If you are creating an entity bean based on a database table, 
the wizard defaults these names to the database table name 
as the Base name and then uses the rules defined in “How 
the wizard names EJBs” on page 19 just above 





Logical EJB name 








Accept the default or provide a legal name 
This name is used: 
e For comments in the wizard-generated code 


e As the <ejb-name> element in the deployment descriptor 
(when used within the scope of an open project) 
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Option What to do 

Implementation class Accept the default or specify a legal Java class name 
Create primary key Check this when you want the EJB Wizard to create a 
class separate primary key class 

Primary key class Accept the default or specify a legal Java class name 





2. If you are creating an entity or session bean that uses CMP 2.x, you are prompted to select 
the radio button (on the bottom portion of this panel) that represents the set of interfaces 
that you want the wizard to generate. 

3. Accept the default names for the set of interfaces, or specify legal Java names. 

4. Click Next to continue. 


Return to “Panel sequence” on page 2. 


Specifying methods 


This panel lets you specify the methods that the wizard will add to the bean implementation 
class and the remote and/or local interface. Methods on the remote and/or local interface can be 
called by the EJB’s client. 


Specify the methods which will be in your message or session 
bean. EJB clients will call any session bean methods to 
execute the functionality that your EJB provides. 








= Back Next> Gancel Help 
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> To complete this panel: 
1. On this panel of the EJB Wizard, click Add and specify the details of one method at a 




















time: 

Option What to do 

Method name Specify a legal method name 

Scope This value must be public so that the method is available to external 
clients; use the Java Editor to specify any nonpublic methods 

Return type Select the method’s return type 

Parameters Click Add to specify the following values for the parameter: 
e Type—Specify the parameter’s data type 
e Name—Specify a legal name for the parameter 

Exceptions Click Add to specify the Exceptions that are thrown by this method 
You do not need to add the java.rmi.RemoteException; it is added 
to the remote interface by default 














2. Click OK to create the methods. 


3. Repeat these steps to create other methods or click Next to continue. 


Return to “Panel sequence” on page 2. 
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Specifying persistent (data) fields 


This panel lets you specify the CMP entity bean’s persistent fields or the BMP entity bean’s data 
fields. This panel is already populated if you base the bean on a database table. Otherwise, you’ ll 
have to use the Add button to add the fields you want. 


List the EJB's data fields here. (The "container managed" 
column is not used for bean-managed EJBs.) The generated 
code will use these fields in the order that they are listed. 











Check All | 
Uncheck All | 





ick Next> Cancel Help 
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> To complete this panel: 
1. Specify: 





Option 


What to do 





Persistent field 


If the fields that should be managed by the container are listed, 
make sure the check box in the container-managed column is 
checked 


Use the Check All/ Uncheck All and Add/Delete buttons to 
manage the list of container-managed data fields 


Use the Up/Down buttons to move the fields to the appropriate 
position if the entity bean should have a composite key 


Container-managed fields are listed in the deployment 
descriptor and can be mapped to a database field at 
deployment time 





Type 


When adding a new field, provide the Java data type. The data 
type must be the Java type that corresponds to the field’s 
JDBC type. For a list of the data types,see the javadoc for 
java.sql.Types. 





Container managed 








Check or uncheck the fields as needed 








2. Click Next to continue. 


Return to “Panel sequence” on page 2. 


Specifying primary key fields 


This panel lets you specify the fields that make up the entity bean’s primary key. 
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Indicate which fields are part of the EJB's primary key. If you 
don't specify any primary key fields, you will have to specify 
the primary key class at deployment time. 
























[7 Use this single field directly as the primary key. 





K Next> 





Gancel’ Help 
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> To complete this panel: 


1. Specify the following information for each field that is part of a primary key field: 











Option What to do 
Field Move the cursor to the field 
Primary Key Depends on how you responded to the Create primary key 


checkbox on the wizard panel described in “Specifying the EJB 
class and interface names” on page 18. If you: 


e Checked the Create primary key class checkbox, you can 
check one or more fields to be included in the primary key class 
that the wizard will generate. 


e If you select a single field for the primary key, you must also 
select the Use this single field... checkbox at the bottom of 
the wizard panel described below. 


e Did not check the Create primary key class checkbox, you can 
do either of the following: 


e Select a single field for the primary key. You must also select 
the Use this single field... checkbox at the bottom of the 
wizard panel described below. 


e Unselect any primary key fields. The wizard will generate 
code that uses a primary key class of type java.lang.Object. 
You will have to specify the primary key class type at 
deployment. 





Use this single 
field directly as 
the primary key 








Check this if you’ve selected a single field that the wizard should 
use as the primary key. 


The field must be a String or a wrapper class for a primitive type 
(such as java.lang.Integer). The wizard generates the code so that 
the wrapper-class type is in the deployment descriptor’s <prim- 
key-class> element and the primary key field name is in the 
<primkey-field> element. 





2. Click Next to continue. 


Return to “Panel sequence” on page 2. 
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Specifying fields that require get/set methods 


This panel lets you specify the fields for which the wizard should generate accessor (get/set) 


methods. 











Indicate the fields for which the EJB Wizard should generate 
get and set methods in the remote interface. Normally you 
will not have get & set methods for primary key fields. 


Field |___ Get method | Set method | 
LEAGUEID | m 

NAME M | 
SPOR vi 









ST 





Check All Gets | 
Uncheck All Gets | 


Check All Sets | 
Uncheck All Sets | 


Cancel Help 


> To complete this panel: 


1. Specify the following information for each field that requires a get or set method: 





Option What to do 





Field Move the cursor to the field 
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Option 


What to do 





Get method 


Specify whether the wizard should generate (checked) a get method 
for this data field 


If your entity bean will be doing any kind of read-only or read-write 
data access on this data field, you should have the wizard generate a 
get method 





Set method 








Specify whether the wizard should generate (checked) a set method 
for this data field 


If your entity bean will be doing updates on this data field, you 
should have the wizard generate a set method 





2. Click Next to continue. 





Return to “Panel sequence” on page 2. 


Specifying create() methods 


This panel lets you specify the create() methods that the wizard should generate. 


Specify the create methods that the EJB Wizard should 
generate. These methods create new database entries. EJB 
clients use them via the EJB's home interface. 













create(LEAGUEID) 


Edit... 


Gancel Help 
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> To complete this panel: 


1. 


3. 
4. 


Click Add to define a new create() method. 


OR 


Highlight an existing create() method and click Edit. 


The Create Method Detail panel appears. 


On the Create Method Detail panel, specify: 





Option 


What to do 





Field 


Move the cursor to the field and check or uncheck the 
fields that should be included in the create() method 
generated by the EJB Wizard 





Do not delegate—generate 
code for this create method 


For bean-managed entity beans only 


Click this radio button if you want the EJB Wizard to 
generate skeleton code for this create() method using 
the checked fields 





Delegate to another create 
method 








For bean-managed entity beans only 


Click this radio button if you do not want the EJB 
wizard to generate skeleton code for this create() 
method, then select the method to call instead from the 
dropdown 





Click OK to return to the create() methods panel. 


Click Next to continue. 


Return to “Panel sequence” on page 2. 
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Specifying relationships 


This panel lets you specify values for the <relationships> node in the EJB deployment 
descriptor. Relationships exist between two entity beans with container-managed persistence. 
However, when you use the EJB Wizard, you are creating a single bean at a time so you can only 
define the <relationship> node entries for the bean you are currently creating. You can define a 
relationship from the current bean to a preexisting bean or a not-yet-defined bean. For the 
related bean, you can use the name you know you will be giving it later, or you can use the 
default name EBUnspecified. When you use EBUnspecified, the wizard generates an 
incomplete relationship node in the deployment descriptor. 


Relationships can be defined as bidirectional or unidirectional. 


How to define bidirectional and unidirectional relationships In a bidirectional 
relationship, each bean knows about the other bean in the relationship. Each bean has methods 
for accessing the relationship field of the other bean. The wizard can generate these accessor 
methods when you define a relationship field for boths sides of the relationship. The relationship 
field is represented in the wizard as the CMR field name. 


In a unidirectional relationship, only one bean in the relationship knows about the other bean. 
An example of a unidirectional relationship is between lineitem and a product. The lineitem 
needs to know about the product, but the product does not know about the lineitem. In a 
unidirectional relationship, you would define a relationship field (a CMR field name) for the 
lineitem bean, but not for the product. 


Editing bean relationships The wizard allows you to edit only the relationships listed in 
the deployment descriptor that are considered incomplete and that: 


e Have the same bean name as the bean you are creating 
OR 


e Use a bean name that does not already exist 
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This list shows existing relationships in the deployment 
descriptor which involve the current bean or a non-existent 
bean. If you wish, you may edit or delete these relationships 
or add new ones. 






‘eam-player (<EBTeam:players> - <EBPlayer:team=) 


Add... 


Edit... 


Delete... | 


Next>) Cancel Help 


> To complete this panel: 


1. To add a relationship, choose Add. 


2. To edit or delete a relationship, highlight the relationship and choose the button 
appropriate to the action you want. 


The Relationship Detail panel The wizard requires the following elements to generate 
accessor methods if this is part of a bidirectional relationship, or if it is unidirectional and is the 
bean that knows about the other bean: 

e The CMR field name for the bean you are creating 

e Whether you require a get and/or a set method 


e The get/set methods return/param type 
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You can fill all of the other information in later using the Deployment Descriptor Editor. 


3% Relationship Detail x| 


Specify the details of this relationship. 



















Relationship name: 


feaque-unspecified 


Relationship role 1: 





Multiplicity: @ One C Many 

EJB name: pesce = =: ëH 

Cascade delete: O 

CMR field name: DOSS O 

Access methods: [> Get method [7 Set method 

Return/param type [© ë 
Relationship role 2: 





Multiplicity: @ One C Many 
EJB name: Feunspecitied X | 


Cascade delete: D 


CMR field name: | 





(OK) Cancel) Help | Gancel) Help 





32 


EJB Wizard 


eXtend Workbench Tools Guide 





> To complete this panel: 


1. Specify: 





Option 


What to do 





Relationship name 


Enter a unique name that identifies the relationship you 
are constructing. 


This corresponds to the <ejb-relation-name> element 
in the Deployment Descriptor. This element is not 
required by the Deployment Descriptor or the wizard. 


For each relationship, you must specify two beans. 





Relationship role 1 





Multiplicity 


Enter the cardinality of the relationship from the 
current bean (the one you are creating) to the related 
bean; it can be One or Many. 


This corresponds to the <multiplicity> element in the 
deployment descriptor. 





EJB name 


Enter the bean name. The bean name entered here must 
always match an <ejb-name> element in the 
enterprise-beans section of the deployment descriptor. 


The wizard adds this entry to the to the <ejb-name> 
element of the <relationship-role-source> element in 
the deployment descriptor. 





Cascade delete 








Check this if you want the current bean to be deleted 
when the related bean is deleted. 


This is only available when the related bean’s 
multiplicity is One. 


This corresponds to the <cascade-delete> element of 
the deployment descriptor. 
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Option 


What to do 





CMR field name 


If this bean is in a bidirectional relationship or is in a 
unidirectional relationship and knows about the related 
bean, then enter a name that begins with a lowercase 
letter. 


The wizard uses the name to generate methods for 
accessing the related bean. This corresponds to the 
<cmr-field-name> element of the cmr-field node in the 
deployment descriptor. 





Access methods 


If a cmr-field is specified, you must create set and/or 
get methods. Otherwise, no accessor methods are 
needed. 





Return/param type 


The return type must be the local interface of the 
related bean or a java.util.Collection type (depending 
on the related bean’s multiplicity. 





Relationship role 2 








Multiplicity Enter the cardinality of the relationship of the related 
bean to the bean you are creating. It can be One or 
Many. 

EJB name Enter the bean name. 


This should match an <ejb-name> element in the 
enterprise-beans section of the deployment descriptor 
(although it might not exist yet). 





Cascade delete 


Check this check box if you want this bean removed 
when the current bean is removed. 





CMR field name 








If this bean is in a bidirectional relationship or is in a 
unidirectional relationship and knows about the current 
bean, then enter a name that begins with a lowercase 
letter. 


The wizard uses the name to generate methods for 
accessing the related bean. This corresponds to the 
<cmr-field-name> element of the cmr-field node in the 
deployment descriptor. 
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2. Click OK to return the relationship panel. 
3. Click Next to continue. 


Return to “Panel sequence” on page 2. 


Specifying find() methods 
This panel lets you define the bean’s finder methods. 


Specify the find methods that the EJB Wizard should 
generate. These methods search the database for specific 
entries. EJB clients use them via the EJB's home interface. 













findByPrimaryKey(pk) 


Gancel Help 





> To complete this panel: 


1. On this panel of the EJB Wizard, click Add to define a new find() method. 
OR 
Highlight an existing find) method and click Edit. 
The Find Method Detail panel appears. 
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2. On the Find Method Detail panel, specify: 














Option What to do 

Method name Specify a legal Java method name 

Returns Click the radio button associated with the Java type that is returned 
Method Click Add to enable the parameter type and name text box, then 


parameters type | specify the Java data type of the parameter 





Method Specify a legal Java parameter name 
parameter name 














3. Click OK to return to the find) methods panel. 
4. Click Next to continue. 


Return to “Panel sequence” on page 2. 


Specifying additional classes or packages to import 


This panel is used to specify any other classes or packages you want the wizard to generate 
import statements for. The wizard does not import any packages by default. 


Specify additional classes and packages to import. 


Additional imports: 


Class or Package to Import 





Add 


Delete | 





Next> Cancel Help 
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> To complete this panel: 


1. Click Add to specify classes or packages to import. 


2. Type the fully qualified path name of the Java class or the full package name in the text 
field. 


3. When you are done adding or removing additional classes or packages, click Next to 
continue. 


Return to “Panel sequence” on page 2. 


Specifying resource references 


This panel lets you specify the resource reference that yov’ll use as a substitute for the database 
table name in the bean’s source code, the connection factory class, and the type of 


authentication. 


Since you have a bean-managed entity EJB, you'll want to 
use a resource reference to refer to the database table name 
in the EJB's source code. Provide the details of this resource 
reference here. 


Database resource reference name: Jac EAGUEDE 


Connection factory class: Javax.sql DataSource 
Database authentication: 

@ Container 

© Application 





kK Next® Cancel Help 
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> To complete this panel: 








1. Specify: 
Option What to do 
Database Specify the name that will be put in the JNDI environment and 
resource looked up by anyone trying to get the named resource 


reference name 


The EJB specification recommends that this be prefaced with 
jdbc/—for example: 


jdbc/MyDataSource 


The deployer will later map this reference to the appropriate 
database 





Connection 
factory class 


Specify the Java type of the factory (not of the resource) 





Database 
authentication 








Specify who performs the login to the resource: 


e Specifying container means the container signs on to the 
resource manager in order to obtain the resource factory 


e Specifying application means the code in the EJB signs on to 
the resource manager programmatically 








2. Click Next to continue. 


Return to “Panel sequence” on page 2. 
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Completing the EJB 


This panel shows you all of the classes and interfaces that the wizard will generate. Review it 
carefully to make sure that you have specified everything that you wanted to. If you find a 
mistake, you can click the Back button to return to a panel and make the appropriate change. 


ZZ EJB Wizard Eg 


Summary 


You have chosen to create the following EJB: 





Session EJB, stateless 


EJB name: SBleague 

Class names: 

Implementation: SBleagueBean 
Remote: SBleague 

Home: SBleagueHome 


are com 
ackage (EJB-client JAR): com 


heels C:\4ries'DocExampleisrcicom 
irectory (EJB-client JAR): C:\Aries\EJBicom 


{Add EJB JAR to existing project: DocExample 


Re not use a project file for EJB-client JAR. 
ession EJB methods: 








sh Cancel Help 


> To complete the EJB: 


1. Check the values in the Summary panel to make sure you have specified everything 
correctly and then click Finish. 

2. When the Summary panel reports the wizard is done creating the EJB, click OK. 
Now the EJB implementation class and the interfaces are open for editing in the Java 
Editor. 


Return to “Panel sequence” on page 2. 
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JSP Wizard 


Use the JSP Wizard to create JSP pages. The following sections describe: 


e About the JSP Wizard 

e Starting the JSP Wizard 

e Specifying the JSP page name and other options 
e Specifying the project, directory, and package 

e Specifying imports 

e What happens 


About the JSP Wizard 


Use the JSP Wizard to quickly specify a variety of attributes for your JSP page and add your JSP 
page to an open project. 


Starting the JSP Wizard 


> To start the JSP Wizard: 


1. Choose File>New. 

2. On the J2EE tab, choose JSP and click OK. (Alternatively, you can double-click JSP.) 
The first panel of the JSP Wizard displays. 

3. Continue as described in “Specifying the JSP page name and other options” on page 40. 


Specifying the JSP page name and other options 


> To specify the JSP page name and other options: 
1. On the first panel of the JSP Wizard, specify the following options: 





Option What to do 





JSP name Specify the name for the JSP page. You don’t need to 
specify the .JSP extension. 
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Option 


What to do 





Page title 


Specify the text for the JSP page’s title. 


Generated as <title>text</title>. 





Content type 


Specify the MIME-type of the response generated by the 
JSP page. Choose from the list provided. 


The default is HTML. 


Generated as the contentType attribute of the page 
directive. 





Template 


Specify a code-generation template, if any. 


Your implementation of Workbench may or may not contain 
additional extension templates of classes that are commonly 
used as starting points for applications in your environment. 


LL) For more information on extensibility, see “Extending 
the Workbench toolset and services” on page 50. 





Use session 


Specify whether the JSP page participates in session 
management (in other words, is part of a session). 


Generated as the session attribute of the page directive. 





Thread safe 


Specify whether the JSP page, once compiled into a servlet, 
can respond to multiple simultaneous requests. If not, 
deselect the check box. 


Generated as the isThreadSafe attribute of the page 
directive. 





Form-based page 


Specify whether a simple HTML form is generated on the 
JSP page (enabled only if you are generating an HTML or 
XHTML page). 





Create error page 








Specify whether an error page is generated for this JSP page 
(enabled only if you are generating an HTML or XHTML 
page). The error page is displayed if an uncaught error 
occurs when the server is processing the JSP page. 


Generated as the errorPage attribute of the page directive. 











JSP Wizard 


41 


4 Component Wizards 








Option 


What to do 





Specify import values 








Specify whether you want to specify Java classes and 
packages to import so that you can reference classes in the 
JSP page without having to explicitly specify package 
names. If you select this option, you will see an additional 
panel in the wizard where you can specify the classes and 
packages. 








2. Click Next to proceed to the next wizard panel. See “Specifying the project, directory, and 


package” on page 42 for details. 


Specifying the project, directory, and package 


> To specify the project, directory, and package: 


1. On this panel of the JSP Wizard, specify the following options: 





Option 


What to do 





Add to open WAR project 


If you currently have one or more Web archive 
(WAR) projects open in Workbench, you can add 
the JSP page to one of those projects by selecting it 
from the list. 





Create project 


If you do not have a WAR project open in 
Workbench but want to associate the JSP page with 
a WAR project, click Create project to start the 
New Project Wizard. 


LL) See “Creating projects and subprojects” on 
page 56 for details. 





No project—just write files to 
the disk. 








Choose this option if you do not want to associate 
the JSP page with a project; the wizard will create 
the JSP page in a nonproject directory on the file 
system. 
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Option 


What to do 





Base directory 


If you specified a WAR project, the default base 
directory is the sre subdirectory of the project 
directory. Otherwise, this field is empty. 


Click Browse to specify a file system location. 


You can add one or more subdirectories to the 
default base directory. 





Package 


Specify a package hierarchy (with levels separated 
by periods) to place the JSP page in a subdirectory 
of the base directory. 


This affects only the directory where the JSP page 
is saved and the default URL for accessing the JSP 
page. The JSP page itself is unaffected. 


For example, if the base directory is 
ProjectDir/\sps and you specified com.myco as the 
package, the JSP page will be created in 
ProjectDir/\sps/com/myco. 





File directory 


The contents of Base directory and Package are 
combined to specify the location of the JSP page, 
which is displayed under File directory. 


This is the file system location where the wizard 
creates the JSP page. 


You cannot change the contents of this field 
directly; you must change Base directory and/or 
Package. 





Add the files to the root of the 
archive 


When generating the project archive, place the JSP 
page at the root of the archive (taking into account 
any package structure you specified). 








Add the files to the archive with 
this prefix 





When generating the project archive, place the JSP 
pages in a directory tree as specified in the prefix 
(taking into account any package structure you 
specified). 
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Option What to do 





The files will be added to this The location in the archive of the JSP page, as 
location in the archive specified by the two preceding selections, are 
reflected in this field. 


You cannot change the contents of this field 
directly; you must change the preceding two 
selections. 














If on the first panel you specified that you want to specify import values, click Next to 
proceed to the next panel. See “Specifying imports” on page 44. 


Otherwise, you are done. Click Finish. When the final wizard panel reports that it has 
finished creating the JSP page, click OK. See “What happens” on page 44. 


Specifying imports 


> To specify classes and packages to import: 


1. 


On this panel of the JSP Wizard, specify which classes you want to reference in the JSP 

page without having to specify their package names. 

Classes or packages you specify here are generated as the import attribute of the page 

directive. This directive corresponds to import statements in a Java source file. 

NOTE As a convenience, every JSP page automatically imports all the classes from 
these packages: java.lang, javax.servlet, javax.servlet.http, and javax.servlet.jsp. 

To add a class or package, click Add and specify the class or package. You can add as 

many classes or packages as you want. 

Click Finish. When the final wizard panel reports it has finished creating the JSP page, 

click OK. See “What happens” on page 44. 


What happens 


The JSP page is generated and appears in the JSP Editor. If you specified that you wanted 
an error page associated with the JSP page, the error page is generated in the same 
directory with the name JSPPageNameErrorPage.jsp and is specified in the JSP page’s 
errorPage attribute of the page directive. 


The wizard adds the JSP page (and error page if present) to the open project if you 
selected that option. 
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Serviet Wizard 


Use the Servlet Wizard to create servlet Java class files. Topics discussed in this section include: 


About the Servlet Wizard 

Starting the Servlet Wizard 

Specifying the class name and other servlet options 
Specifying the project, directory, and package 
Specifying which HttpServlet methods to override 
Specifying which interfaces to implement 


Specifying which classes and packages to import 


About the Servlet Wizard 


The Servlet Wizard provides an automated mechanism for creating Java servlet source files. The 
wizard provides options to specify these attributes of a Java servlet class: 


The content type of the HTTP response document, such as HTML, XML, and so on 
Whether to implement the single- or multi-threaded model interface 


Whether to include the servlet in an existing Workbench project, in a new project, or not in 
any project 


Whether the servlet is to be a member of a package (that is, whether to specify a package 
definition) 

The directory structure for the Java source files and for the generated classes in the archive 
Whether to override specified HttpServlet methods 

Whether to implement any interfaces 


Whether to import any classes or packages 


Once you have created a servlet using the Servlet Wizard, you can modify that servlet in the Java 


Editor. 
LL) For details about editing servlets in Workbench, see Chapter 6, “Source Editors” in this 


book and the chapter on writing servlets in the Development Guide. 
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Starting the Servlet Wizard 


> To start the Servlet Wizard: 


1. Choose File> New. 


2. On the J2EE tab, choose Servlet and click OK. (Alternatively, you can double-click 
Servlet.) 


3. To continue, see “Specifying the class name and other servlet options” on page 46. 


Specifying the class name and other serviet options 


> To specify the class name and other servlet options: 


1. On the first panel of the Servlet Wizard, specify the following options: 














Option What to do 
Class name Specify an appropriate name for the servlet class. 
Content type Specify the type of the document content of the 
HTTP response the servlet is to generate. 
The default is HTML. 
Template Specify a code-generation template, if any. 


Your implementation of Workbench may or may 
not contain additional extension templates of 
classes that are commonly used as starting points 
for applications in your environment. 


LL) For more information on extensibility, see 
“Extending the Workbench toolset and services” 
on page 50. 

















46 Servlet Wizard 


eXtend Workbench Tools Guide 








Option What to do 





Implement SingleThreadModel | Specify whether the servlet class is to implement 
the SingleThreadModel interface. 


Implementing this interface guarantees that no 
more than one request thread accesses a single 
instance of your servlet. While this can guarantee 
that servlet fields are accessed by only one thread 
at a time, there can be significant performance 
costs if your servlet is accessed frequently. 


The default is to allow multithreaded access to the 
servlet. 














2. Click Next to go to the next wizard panel. See “Specifying the project, directory, and 
package” on page 47. 


Specifying the project, directory, and package 


> To specify the project, directory, and package: 


1. On the second panel of the Servlet Wizard, specify the following options: 





Option What to do 





Add to open WAR project If you currently have one or more Web Archive 
(WAR) projects open in Workbench, you can add 
the servlet to one of those projects by selecting it 
from the list. 





Create project If you do not have a WAR project open in 
Workbench but want to associate the servlet with a 
WAR project, you can click Create project to start 
the New Project Wizard. 


LL) For details, see “Creating projects and 
subprojects” on page 56. 
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Option 


What to do 





No project—just write files to 
the disk. 


If you do not want to associate the servlet with any 
Workbench project, you can still use the wizard to 
create a servlet class anywhere on the file system. 





Base directory 


If you specified a WAR project, the default base 
directory is a sre subdirectory located directly 
under the project directory. Otherwise, this field is 
empty. 


Click Browse to specify a file system location. 


You can add one or more subdirectories to the 
default base directory. 








Package If your servlet is to be a member of a package (for 
example, com.mwbi.welcome), specify the 
package name in this field. 

File directory The contents of Base directory and Package are 


combined to specify the location of the servlet 
source file, which is displayed under File 
directory. 


This is the file system location where the wizard 
creates the servlet source file. 


You cannot change the contents of this field 
directly; you must change Base directory and/or 
Package. 





Add the files to the root of the 
archive 








When generating the project archive, place the 
generated class files for the servlet at the root of 
the archive. 
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Option 


What to do 





Add the files to the archive with 
this prefix 


When generating the project archive, place the 
generated class files for the servlet in a directory 
tree as specified in the prefix. 


The default is to place the servlet classes in a 
WEB-INF’/classes directory under the root of the 
archive. 


If you specified a package name, the directory 
structure associated with that package is added to 
the prefix to determine the final archive path for 
the generated classes. 





The files will be added to this 
location in the archive 








The location in the archive of the generated servlet 


class files, as specified by the two preceding 
selections, are reflected in this field. 


You cannot change the contents of this field 
directly; you must change the preceding two 
selections. 








Click Next to go to the next wizard panel. See “Specifying which HttpServlet methods to 


override” on page 49. 


Specifying which HttpServiet methods to override 


> To specify which HttpServlet methods you want to override: 


1. 


On this panel of the Servlet Wizard, specify which methods in the HttpServlet class to 


override in the servlet. 


Typically, you want to override the doGet and doPost methods. This panel enables you to 


override these HttpServlet methods: 


e  doGet 

e  doPost 

e doPut 

e doDelete 
e init 

e destroy 
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e — getServletInfo 


Choosing any of these methods causes the wizard to insert the basic structure for that 
method into the servlet code it generates so that you can easily add the appropriate 
processing logic later using the Java Editor. 


Click Next to go to the next wizard panel. See “Specifying which interfaces to implement” 
on page 50. 


Specifying which interfaces to implement 


> To specify which interfaces to implement: 


1. 


On this panel, specify any interfaces that the servlet will implement. Click Add to specify 
an interface. You must specify the fully qualified name of the interface. For each interface, 
you can specify whether you want the wizard to generate stub methods. 


You can rearrange the list of interfaces by clicking Up or Down. You can specify that you 
want stub methods for all or none of the interfaces by clicking Check All or Uncheck All. 


The wizard will generate the following for each interface you specify: 

e Anentry in the servlet’s implements statement 

e All necessary imports 

e — Stub code for all interfaces where you checked Generate Stub Code 


Click Next to go to the next wizard panel. See “Specifying which classes and packages to 
import” on page 50. 


Specifying which classes and packages to import 


> To specify which classes and packages to import: 


1. 


On this panel, specify any additional classes or packages that the servlet should import. 
The wizard will generate an import statement for each entry you make here. 

Once you have specified the imports, click Finish. 

The Servlet Wizard creates a Java servlet class based on what you specified. 

When the wizard reports that it is done creating the servlet, click OK. 

The servlet code appears in the Java Editor. 


If you specified that the servlet is to be associated with a WAR project, the wizard adds the 
servlet to that project. 
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Java Class Wizard 


Use the Java Class Wizard to create general-purpose Java class files. The following sections 
describe: 

e About the Java Class Wizard 

e Starting the Java Class Wizard 

e Specifying the class name and other options 

e Specifying which interfaces to implement 

e Specifying which classes and packages to import 


e Specifying the project, directory, and package 


About the Java Class Wizard 


With the Java Class Wizard you specify a variety of class attributes such as scope and whether 
to create a class or an interface. The wizard lets you add the new source file to an existing 
project, create a new project to add the new source file to, or simply write the new class file to 
disk. 


Starting the Java Class Wizard 


> To start the Java Class Wizard: 


1. Choose File> New. 


2. On the J2EE tab, choose Java file and click OK. (Alternatively, you can double-click 
Java file.) 


3. Continue as described in “Specifying the class name and other options” on page 52. 
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Specifying the class name and other options 


> To specify the class name and other options: 


1. On the first panel of the Java Class Wizard, specify the following options: 











Option What to do 
Class name Specify an appropriate name for the Java class. 
Base class Specify the base class, if any. You can enter a simple or a fully 


qualified name. 





Create class or 
interface? 


Specify whether to create a class or an interface. 





Template 


Specify a code-generation template, if any. 


Your implementation of Workbench may or may not contain 
additional extension templates of classes that are commonly used 
as starting points for applications in your environment. 


LL) For more information on extensibility, see “Extending the 
Workbench toolset and services” on page 50. 





Bottom group 
(check boxes) 








Use any of the following check boxes to further specify class 
attributes: 


e Public scope 
e Create a default constructor 
e Create main() method 


e Serializable 








2. Click Next to go to the next wizard panel. See “Specifying which interfaces to implement” 


on page 53. 
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Specifying which interfaces to implement 


> To specify which interfaces to implement: 


1. On this panel, specify any interfaces that the class will implement. Click Add to specify 
an interface. You must specify the fully qualified name of the interface. For each interface, 
you can specify whether you want the wizard to generate stub methods. 


2. You can rearrange the list of interfaces by clicking Up or Down. You can specify that you 
want stub methods for all or none of the interfaces by clicking Check All or Uncheck All. 


The wizard will generate the following for each interface you specify: 

e Anentry in the class’s implements statement 

e All necessary imports 

e Stub code for all interfaces where you checked Generate Stub Code 


3. Click Next to go to the next wizard panel. See “Specifying which classes and packages to 
import” on page 53. 


Specifying which classes and packages to import 


> To specify which classes and packages to import: 


1. On this panel, specify any additional classes or packages that the class should import. 
The wizard will generate an import statement for each entry you make here. 


2. Click Next to go to the next wizard panel. See “Specifying the project, directory, and 
package” on page 53. 


Specifying the project, directory, and package 


> To specify the project, directory, and package: 


1. On the top portion of this panel of the Java Class Wizard, specify one of the following 
three project association options: 





Option What to do 





Add to open project If you currently have one or more projects open in 
Workbench, you can add the class file to one of those 
projects by selecting it from the list. 
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Option 


What to do 





Create project 


If you do not have a project open in Workbench but want to 
associate the class file with a project, click Create project 
to start the New Project Wizard. 


When you are through, the new project is selected as the 
project to add the new class file to. 


O] For more information, see “Project design 
considerations” on page 53. 





No project—just write 
the files to the disk 








Choose this option if you do not want to associate the class 
file with a project; the wizard will create the class file in a 
nonproject directory on the file system. 





On the lower portion of this Java Class Wizard panel, specify the following options: 





Option 


What to do 





Base directory 


If you specified a WAR project, the default base directory is 
a sre subdirectory located directly under the project 
directory. Otherwise, this field is empty. 


Click Browse to specify a file system location. 


The Base directory is the project root combined with 
whatever other directories are in the project directory 
structure above the package path. 





Package 








Specify the fully-qualified Java package name for the new 
class. You can specify a package hierarchy with levels 
separated by periods. 


The Java class you are creating is saved in the Base 
directory combined with the Package directory. 


For example, if the base directory is ProjectDir/classes and 
you specified com.myco as the package, the class will be 
created in ProjectDir/classes/com/myco. 
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Option 


What to do 





File directory 


The contents of Base directory and Package are combined 
to specify the location of the Java class source file, which is 
displayed under File directory. 


This is the file system location where the wizard creates the 
Java class source file. 


You cannot change the contents of this field directly; you 
must change Base directory and/or Package. 





Add the files to the root 
of the archive 


Adds the compiled Java class file to the archive root 
combined with the package path when generating the 
project archive. 





Add the files to the 
archive with this prefix 


Adds the compiled Java class file to the specified archive 
directory combined with the package path when generating 
the project archive. 


If you specified a package name, the directory structure 
associated with that package is added to the prefix to 
determine the final archive path for the generated class. 





The files will be added 
to this location in the 
archive 








The location in the archive of the generated Java class file, 
as specified by the two preceding selections, are reflected in 
this field. 


You cannot change the contents of this field directly; you 
must change the preceding two selections. 








3. Click Finish. 


4. When the final wizard panel reports it’s done creating the Java class, click OK. 


The code appears in the Java Editor. (The Java class is added to the open project only if 


you selected that option.) 


The wizard creates the Java class source file. After you write the methods that implement the 
specific functionality for this new class (as well as any import statements), you can add the new 


class file to a project. 


LL) For more information, see “Adding to projects” on page 68. 
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JavaBean Wizard 


Use the JavaBean Wizard to create JavaBeans. The following sections describe: 


About the JavaBean Wizard 

Starting the JavaBean Wizard 

Specifying the class name and other options 
Specifying the data fields 

Specifying which interfaces to implement 
Specifying which classes and packages to import 


Specifying the project, directory, and package 


About the JavaBean Wizard 


Use the JavaBean Wizard to quickly create a skeleton for a JavaBean and add it to an open 
project. 


Starting the JavaBean Wizard 


> To start the JavaBean Wizard: 


1. 
2. 


Choose File>New. 


On the J2EE tab, choose JavaBean and click OK. (Alternatively, you can double-click 
JavaBean.) 


The first panel of the JavaBean Wizard displays. 


Continue as described in “Specifying the class name and other options” on page 56. 


Specifying the class name and other options 


> To specify the class name and other options: 


1. 


On the first panel of the JavaBean Wizard, specify the following options: 





Option What to do 





Class name Specify the name for the JavaBean. You don’t need to 
specify the Java extension. 
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Option What to do 





Base class If the JavaBean is inherited from a base class, specify the 
name of the base class. You can specify a simple or fully 
qualified name. 


Generated as extends class. 











Template Specify a code-generation template, if any. 


Your implementation of Workbench may or may not contain 
additional extension templates of classes that are commonly 
used as starting points for applications in your environment. 


LL) For more information on extensibility, see “Extending 
the Workbench toolset and services” on page 50. 








2. Click Next to proceed to the next wizard panel. See “Specifying the data fields” on 


page 57 for details. 


Specifying the data fields 


> To specify the data fields for the JavaBean: 


1. Define each data field by clicking Add and specifying the name and data type. 


The generated Java file will define the fields in the order in which they are listed here. You 
can reorder the list by selecting a field and clicking Up or Down. 


2. Click Next to proceed to the next wizard panel. See “Specifying which interfaces to 


implement” on page 57 for details. 


Specifying which interfaces to implement 


> To specify which interfaces to implement: 


1. On this panel, specify any interfaces that the bean will implement. Click Add to specify an 
interface. You must specify the fully qualified name of the interface. For each interface, 
you can specify whether you want the wizard to generate stub methods. 


2. You can rearrange the list of interfaces by clicking Up or Down. You can specify that you 
want stub methods for all or none of the interfaces by clicking Check All or Uncheck All. 
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The wizard will generate the following for each interface you specify: 

e Anentry in the bean’s implements statement 

e All necessary imports 

e — Stub code for all interfaces where you checked Generate Stub Code 


3. Click Next to go to the next wizard panel. See “Specifying which classes and packages to 
import” on page 58. 


Specifying which classes and packages to import 


> To specify which classes and packages to import: 


1. On this panel, specify any additional classes or packages that the bean should import. 
The wizard will generate an import statement for each entry you make here. 


2. Click Next to go to the next wizard panel. See “Specifying the project, directory, and 
package” on page 58. 


Specifying the project, directory, and package 


> To specify the project, directory, and package: 


1. On the top portion of this panel of the JavaBean Wizard, specify one of the following three 
project association options: 





Option What to do 





Add to open project If you currently have one or more projects open in 
Workbench, you can add the bean to one of those projects 
by selecting it from the list. 





Create project If you do not have a project open in Workbench but want to 
associate the bean with a project, click Create project to 
start the New Project Wizard. 


When you are through, the new project is selected as the 
project to add the new bean to. 


CO] For more information, see “Project design 
considerations” on page 53. 
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Option 


What to do 





No project—just write 
the files to the disk 








Choose this option if you do not want to associate the bean 
with a project; the wizard will create the bean in a 
nonproject directory on the file system. 








2. On the lower portion of this JavaBean Wizard panel, specify the following options: 





Option 


What to do 





Base directory 


If you specified a project, the default base directory is a sre 
subdirectory located directly under the project directory. 
Otherwise, this field is empty. 


Click Browse to specify a file system location. 


The Base directory is the project root combined with 
whatever other directories are in the project directory 
structure above the package path. 





Package 


Specify the fully-qualified Java package name for the new 
bean class. You can specify a package hierarchy with levels 
separated by periods. 


The bean you are creating is saved in the Base directory 
combined with the Package directory. 


For example, if the base directory is ProjectDir/classes and 
you specified com.myco as the package, the bean will be 
created in ProjectDir/classes/com/myco. 





File directory 


The contents of Base directory and Package are combined 
to specify the location of the bean, which is displayed under 
File directory. 


This is the file system location where the wizard creates the 
bean source file. 


You cannot change the contents of this field directly; you 
must change Base directory and/or Package. 





Add the files to the root 
of the archive 








Adds the compiled JavaBean to the archive root combined 
with the package path when generating the project archive. 
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Option What to do 





Add the files to the Adds the compiled JavaBean to the specified archive 
archive with this prefix | directory combined with the package path when generating 
the project archive. 


If you specified a package name, the directory structure 
associated with that package is added to the prefix to 
determine the final archive path for the generated bean. 





The files will be added | The location in the archive of the generated JavaBean, as 
to this location in the specified by the two preceding selections, are reflected in 
archive this field. 


You cannot change the contents of this field directly; you 
must change the preceding two selections. 














Click Finish. 
When the final wizard panel reports it’s done creating the JavaBean, click OK. 


The code appears in the Java Editor. (The JavaBean is added to the open project only if 
you selected that option.) 


The wizard creates the skeleton of the JavaBean source file. The skeleton includes an empty 
constructor, declarations for all the data fields (as m_name), and get and set methods for all the 
fields. 


Tag Handler Wizard 


Use the Tag Handler Wizard to create tag handler classes for custom JSP tags. The following 
sections describe: 


About the Tag Handler Wizard 

Starting the EJB Wizard 

Specifying the class name and other options 
Specifying the project, directory, and package 
Specifying the tag library descriptor file 
Specifying the body type 

Specifying tag handler attributes 

Specifying tag handler scripting variables 
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e Specifying TagExtralnfo class 
e What happens 


About the Tag Handler Wizard 


The Tag Handler Wizard can speed your JSP development effort by: 


e Creating a skeleton of the tag handler class 
e Creating or modifying the associated tag library descriptor file (TLD) 


e Updating the web.xml file to include the required information 


You can edit the tag handler class using the Java Editor. You can modify the TLD or the web.xml 
files using the XML Editor. Both files are in the Project tab of Workbench. 


Starting the Tag Handler Wizard 


> To start the Tag Handler Wizard: 


1. Click File> New. 


2. On the J2EE tab, choose Tag handler and click OK. (Alternatively, you can double-click 
Tag handler.) 


3. Continue as described in “Specifying the class name and other options” on page 62. 
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Specifying the class name and other options 


> To specify the class name and other options: 


1. On the first panel of the Tag Handler Wizard, specify the following options: 





Option 


What to do 





Class name 


Specify the name for the tag handler. The name must be a valid 
Java name. You do not need to specify the .java extension. 


This value is added to the TLD file in the <tagclass> element. 





Tag name 


Specify the name of the custom tag. 


This will appear in the <name> element of the tag definition in the 
tag library descriptor file (TLD). 





Template 


Specify a code-generation template, or accept the default. 


Your implementation of Workbench may or may not contain 
additional extension templates of classes that are commonly used 
as starting points for applications in your environment. 


LL) For more information on extensibility, see “Extending the 
Workbench toolset and services” on page 50. 





Attributes 


Select this check box if the custom tag should support tag element 
attributes. 


If you select this option, you will see an additional wizard panel 
where you can specify the details of the attribute(s). 





Scripting 
Variables 


Select this check box if the custom tag should support scripting 
variables. 


If you select this option, you will see an additional wizard panel 
where you can specify the details of the scripting variable(s). 





Body Tag 








Select this check box if the custom tag will use the content of the 
tag element’s body in a JSP page. 


If you select this option, you will see an additional wizard panel 
where you can specify the details of the body tag(s). 
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2. Click Next to go to the next wizard panel. See “Specifying the project, directory, and 
package” on page 63. 


Specifying the project, directory, and package 


> To specify the project, directory, and package: 


1. On the top portion of this panel of the Tag Handler Wizard, specify one of the following 
three project association options: 





Option What to do 





Add to open project | If you currently have one or more projects open in Workbench, 
you can add the class file to one of those projects by selecting it 
from the list. 





Create project If you want to associate the class file with a new project, click 
Create project to start the New Project Wizard. 


When you are through, the new project is selected as the project 
to add the new class file to. 


C] For more information, see “Project design 
considerations” on page 53. 











No project—just Disabled—you must associate the tag handler class with a 
write the files to the | project. 
disk 








2. On the lower portion of this panel, specify the following options: 





Option What to do 





Base directory The default base directory is the project’s sre subdirectory 
located directly under the project directory. 


Click Browse to specify a file system location. 


The Base directory is the project root combined with 
whatever other directories are in the project directory 
structure above the package path. 
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3. 





Option 


What to do 





Package 


Specify the fully qualified Java package name for the new 
tag handler class. You can specify a package hierarchy (with 
levels separated by periods). 





File directory 


This is the file system location where the wizard creates the 
tag handler source file and the TagExtraInfo class source 
file, if any. 

The tag handler class you are creating is saved in the Base 


directory combined with the Package directory. 


For example, if the base directory is ProjectDir/classes and 
you specified com.myco as the package, the class will be 
created in ProjectDir/classes/com/myco. 


You cannot change the contents of this field directly; you 
must change Base directory and/or Package. 





Add the files to the root 
of the archive 


Adds the compiled tag handler class file to the archive root 
combined with the package path when generating the 
project archive. 





Add the files to the 
archive with this prefix 


Adds the compiled tag handler class file to the specified 
archive directory combined with the package path when 
generating the project archive. 


If you specified a package name, the directory structure 
associated with that package is added to the prefix to 
determine the final archive path for the generated class. 





The files will be added 
to this location in the 
archive 








The location in the archive of the generated tag handler 
class file, as specified by the two preceding selections, are 
reflected in this field. 


You cannot change the contents of this field directly; you 
must change the preceding two selections. 








Click Next to proceed to the next wizard panel. See “Specifying the tag library descriptor 


file” on page 65. 
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Specifying the tag library descriptor file 


> To specify the tag library descriptor file: 


1. On the top portion of this panel of the Tag Handler Wizard, choose one of the following 











options: 
Option What to do 
Use Existing TLD Choose this option when you are adding new custom tags to an 
existing TLD, then specify the TLD name and disk location 
Create New TLD Choose this option when you are creating a new TLD and 
specify the remaining fields 











2. If you chose Create New TLD, complete the following fields: 





Option 


What to do 





Taglib Short Name 


Specify the value to be used in the Tab Library Descriptor 
<short-name> element. 

















Taglib URI Specify a URI that is used in the WAR's deployment 
descriptor. This is not the URI for the TLD file. 
This URI can be used in the JSP taglib directives to refer to 
this taglib. For example, /mytags. 

TLD file name Specify the name of the TLD to create. 

TLD directory Specify the directory location where the wizard should create 


the TLD file. 
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Option 


What to do 





Archive location 


Specify the directory location for the TLD within the archive: 


e When deployed inside a JAR file, the TLD must be in the 
META-INF directory 


e When deployed directly in a WAR file, TLDs are usually 
placed in the \WEB-INF directory or a separate \WEB- 
INF(\tlds directory 





JSP Version to 
support 








Choose the radio button that represents the version of the JSP 
specification that the TLD will support. 


If you are using a WAR project for J2EE 1.2 (servlet2.2 and 
JSP1.1) you cannot change the wizard’s choice of JSP1.1. 








Click Next to go to the next wizard panel. What panel displays next depends on whether 
you checked the attributes, scripting variables, or body tag check boxes on the first wizard 
panel. Follow the first option that fits: 


e Ifthe custom tag uses the tag element’s body content, see “Specifying the body type” 


on page 67. 


e Ifthe custom tag uses tag element attributes, see “Specifying tag handler attributes” on 


page 67. 


e Ifthe custom tag uses or creates scripting variables, see “Specifying tag handler 
scripting variables” on page 68. 


e Otherwise, see “Specifying TagExtralInfo class” on page 69. 





66 


Tag Handler Wizard 


eXtend Workbench Tools Guide 





Specifying the body type 


> To specify the body type: 


1. Specify values for the following options: 





Option What to do 





JSP Specify this option when you want to use JSP code, HTML tags, 
plain text, other custom tags, and any other valid Web page content 
in the body of the custom tag. 





Tag dependent Specify this option when you want to use non-JSP code (like SQL) 
in the body of the custom tag. The tag’s body content will be 
passed directly to the tag handler class without any runtime 
evaluation. 











2. Click Next to go to the next wizard panel. What panel displays next depends on whether 
you checked the attributes or scripting variables check boxes on the first wizard panel. 


e Ifthe custom tag uses tag element attributes, see “Specifying tag handler attributes” on 
page 67. 


e Ifthe custom tag uses or creates scripting variables, see “Specifying tag handler 
scripting variables” on page 68. 


e Otherwise, see “Specifying TagExtralInfo class” on page 69. 


Specifying tag handler attributes 


> To specify the tag handler attributes: 


1. Specify values for the following options: 





Option What to do 





Attribute Specify the name of the attribute. 


This value corresponds to the <attribute> element’s <name> 
element within the TLD entry for this custom tag. 





Type Specify the data type of the attribute. Corresponds to the TLD 
file’s element. The value must be a nonprimitive type. 
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Option What to do 





Required Specify whether the attribute is required when the custom tag is 
used. When checked the attribute is required. Corresponds to the 
TLD file’s <required> element. 





Runtime Specify whether you can use a JSP scriptlet expression in the 
expression JSP page to set the value of the attribute. This corresponds to the 
TLD file’s <rtexprvalue> element. 














2. Click Next to go to the next wizard panel. What panel displays next depends on whether 
you checked the scripting variables check box on the first wizard panel. 


e Ifthe custom tag uses or creates scripting variables, see “Specifying tag handler 
scripting variables” on page 68. 


e Otherwise, see “Specifying TagExtralInfo class” on page 69. 


Specifying tag handler scripting variables 


> To specify tag handler scripting variables: 


1. Specify the values for the following options: 











Option What to do 
Variable Enter the variable’s name. 
Type Enter the variable’s data type. 





New Object | Specify whether the variable refers to a new or existing object instance. 





Scope Specify the availability of the variable. Values can be: 
e NESTED—The variable is available between the start and end tags 


e AT_BEGIN—The variable is available from the start tag until the end of 
the page 


e AT_END—The variable is available after the end tag until the end of the 
page 














2. Click Next to go to the next wizard panel. See “Specifying TagExtraInfo class” on 
page 69. 
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Specifying TagExtralnfo class 


> To specify whether or not to create a TagExtralnfo class: 


1. Specify values for the following options: 








Option What to do 
Do not create Choose this option if you do not want the wizard to create a 
TagExtraInfo class TagExtraInfo class. 





Create TagExtraInfo | Choose this option if you want the wizard to create a 
class TagExtraInfo class. This option might be disabled if your tag’s 
configuration requires a TagExtralnfo class. 


(Optional) Choose the appropriate checkbox if you want the 
wizard to implement either of the following methods: 


e getVariableInfo() 
e isValidQ 














2. Click Finish. When the final wizard panel reports it has finished creating the TagExtraInfo 
class, click OK. 


See “What happens” on page 44. 


What happens 


When you click Finish, the wizard: 


e Generates the tag handler class and displays it in the Java Editor. 


e Generates the TagExtraInfo class associated with the tag handler (if specified). The class 
is generated in the same directory with the name TagHandlerClassNameExtralnfo.java. 


e Adds the tag handler class (and theTagExtraInfoClass if present) to the specified project. 


e Creates a new TLD file (and the WAR’s deployment descriptor is modified) or updates an 
existing TLD file, depending on what you chose. 
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5 Web Service Wizard 





This chapter describes the Web Service Wizard of SilverStream eXtend Workbench, which you 
can use to generate files for implementing and invoking Web Services. Topics include: 

e About the wizard 

e Using the wizard 

e Panel sequence 


e Panel details 


LH Foran introduction to Web Service concepts, standards, and technologies, see the chapter 
on understanding Web Services in the Development Guide. 


About the wizard 


The Web Service Wizard can perform either of these tasks for you: 


e Generate a standard (SOAP-based) Web Service that’s implemented as a Java remote 
object. The wizard creates a servlet to handle access to your Web Service and its methods 
from HTTP SOAP requests. 


e Generate the code needed for a Java-based consumer program to access any standard 
(SOAP-based) Web Service. The generated code handles all HTTP SOAP processing 
under the covers, enabling your consumer program to call the Web Service as a Java 
remote object and invoke its methods. 


In both cases, the wizard produces Java source files based on JAX-RPC (Java API for XML- 
based RPC) and jBroker Web (the JAX-RPC implementation included with SilverStream 
eXtend). JAX-RPC is the J2EE specification that provides Web Service support. 


You can use the generated files as is or modify them when necessary. The advantage of this Java- 
oriented approach is that you can deal with Web Services using the familiar technologies of RMI 
and J2EE instead of coding lower-level SOAP APIs. 
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How it works Behind the scenes, the Web Service Wizard uses several different compilers 


to generate the output you request: 





The wizard uses this 
compiler 


To generate 





Remote interface generator 


A Java remote interface from a JavaBean, Java class, or 
EJB session bean 





wsdl2java (from jBroker Web) 


A Java remote interface from a WSDL file 





xsd2java (from jBroker Web) 


Type classes (JavaBeans, marshalers) and mapping files 
from complex types defined in a WSDL file’s XML 
Schema 





rmi2soap (from jBroker Web) 


Skeleton and tie classes, stub and service classes, as well 
as marshalers (for complex types) from a Java remote 
interface 





rmi2wsdl (from jBroker Web) 








A WSDL file from a Java remote interface 








The wizard determines which compilers to run and in what order depending on the type of input 
you provide and options you select when filling in its panels. 


Alternatives to the wizard 


You can also run the individual wsdl2java, xsd2java, 


rmi2soap, and rmi2wsdl compilers manually from a command line. For more information, see 


the jBroker Web help. 
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Using the wizard 


Here’s where you'll learn about preparing to use the Web Service Wizard, running it, and 


working with its output: 





For instructions on 


See 





Using the wizard to create a new Web Service 
based on one of these: 


e A JavaBean or other Java class 
e An EJB session bean 
e A Java remote interface 


e A WSDL file 


The chapter on generating Web Services 
in the Development Guide 





Using the wizard to create code for accessing 
an existing Web Service based on its WSDL 
file 








The chapter on generating Web Service 
consumers in the Development Guide 





Panel sequence 


This section lists the panels you need to complete in the Web Service Wizard, depending on your 








scenario: 
If you start with You step through these panels 
A JavaBean or other Java class 1. Project location (and possibly WAR project 








selection) 
2. Class selection 
3. Method selection 


4. Class-generation and SOAP options 
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If you start with 


You step through these panels 





The home interface of an EJB 
session bean 


1. Project location (and possibly WAR project 
selection) 


2. Class selection 
3. EJB lookup information 
4 


. Class-generation and SOAP options 





The remote interface of an EJB 
session bean or the SessionBean 
class itself 


1. Project location (and possibly WAR project 
selection) 


2. Class selection 

3. EJB home interface selection 
4. EJB lookup information 
5 


. Class-generation and SOAP options 





A Java remote interface 


1. Project location (and possibly WAR project 
selection) 


2. Class selection 


3. Class-generation and SOAP options 





A WSDL file 








1. Project location 


2. WSDL file selection (and possibly Multiple 
namespace mapping) 





3. Class-generation and SOAP options 
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Panel details 


This section describes the options on each panel of the Web Service Wizard. The panels are: 


Project location 

WAR project selection 

Class selection 

WSDL file selection 

Multiple namespace mapping 

EJB home interface selection 

EJB lookup information 

Method selection 

Class-generation and SOAP options 


Project location 


This panel is used to specify details about the project location (project, directory, package) 
where the wizard is to store Web Service files it generates. There are two variations of this panel: 


If you start with a WSDL file, you'll see: 


3% Web Service Wizard Eg 


Specify the project, package, and base directory for the 
generated classes. 





( Add to open project: [WebServiceConsumerSample z] Create project... | 


@ No project -- just write files to the disk 








Base directory: FtextendProjects WebServiceConsumerSampletsrc z] Browse... | 
Package: Fom.exsamp.use 


File directory:  C:\eXtendProjectsWebServiceConsumerSample\src\icomexsampuse 
NOTE: The entire contents of this directory will be included in the archive. 


@ Add the files to the root of the archive. 


© Add the files to the archive with this prefix: | 


The files will be added to this location in the archive: 
comexsampluse 





package 








aS Next> Cancel Help 
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If you start with anything else (JavaBean, Java class, EJB session bean, or Java remote 


interface), you'll see: 


ZZ Web Service Wizard Eg 


Specify the WAR or JAR project and base directory where 
the new Web Service classes should be added. 


f Add to open project: [WebServiceSample z] Create project... | 



















@ No project -- just write files to the disk 
Base directory: [eXtendProjects WebServiceSampletsrc z] Browse... | 
Package | 


File directory: C:\eXtendProjectsWVebServiceSampletsrc\ 
NOTE: The entire contents of this directory will be included in the archive. 


@ Add the files to the root of the archive 





@ Add the files to the archive with this prefix WWEB-INF iclasses 














Next> Cancel Help 





In this variation, you don’t specify a package (because the wizard will get this information 


from your class or interface, which you supply on an upcoming panel). 
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> To complete this panel: 


1. 








Specify the project: 
Option What to do 
Add to open Select a project where the wizard is to store generated files. This 


project 


option lets you choose from a list of the projects currently open in 
Workbench. 


If you’re generating a Web Service, you’ ll typically select a 
WAR project. 


When appropriate, you can select a JAR project instead, but then 
the wizard will prompt for a WAR project to map the Web 
Service’s servlet. See “WAR project selection” on page 9. 


(When you generate a Web Service from a WSDL file, the wizard 
does not currently support selecting a JAR project. It requires you 
to select a WAR project.) 


If you’re generating a Web Service consumer, you can select 
any type of project. 





Create project 


Click this button if you want to create a new project to use. It 
displays the New Project dialog. 


See “Creating projects and subprojects” on page 56. 





No project -- 
just write files to 
the disk 








(This option is disabled. In the Web Service Wizard, generated 
files must be added to an open project.) 


























2. Specify the directory and package: 

Option What to do 

Base directory The default base directory is a sre subdirectory located right under 
the project directory on your file system. If you want to select a 
different file system location, click Browse. 

Package (If enabled) Specify the fully-qualified Java package name to be 
used for generated classes (for example, com.myco.mypkg). 
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Option What to do 

File directory This informational field shows the file system location where 
generated files will be stored. It is the result of combining Base 
directory and Package. 

Add the files to | (If enabled) Choose this option to place the generated files (and 

the root of the their package path, if any) at the root of the project archive. 

archive 

Add the files to | Choose this option to place the generated files (and their package 


the archive with 
this prefix 


path, if any) under a specified directory structure (prefix) in the 
project archive. 


For a WAR project, the prefix is automatically set to WEB- 
INF/classes. 














The files will be | (If displayed) This informational field shows the project archive 
added to this location where generated files will be stored. It is the result of 
location in the combining Prefix and Package. 
archive 

Click Next. 





Panel details 





eXtend Workbench Tools Guide 





WAR project selection 


This panel is used to specify the required WAR project for a Web Service stored ina JAR 
project. The wizard will update this WAR’s deployment descriptor (web.xml) with the servlet 
mapping for the Web Service. 


3% Web Service Wizard |x} 


The project you have selected is not a WAR project. 
Please select the WAR that the generated servlet will be 


available in. 


WAR project: Jmywar z] Create project... | 





Next= Cancel Help 


> To complete this panel: 


1. Specify the following: 





Option 


What to do 





WAR project 


Select the WAR project for the Web Service’s servlet mapping. 
This option lets you choose a WAR project currently open in 
Workbench. 





Create project 








Click this button if you want to create a new WAR project to use. It 
displays the New Project dialog. 


LL) See “Creating projects and subprojects” on page 56. 





2. Click Next. 
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Class selection 


This panel is used to select a compiled class from which the wizard is to generate Web Service 
files. Supported choices include: 

e A JavaBean or other Java class 

e An EJB session bean interface or class 


e A Java remote interface 


Select the class from which you would like to generate 
new Web Service classes. 


Available Classes (2) 


class com.exsamp.obj. MyObject 


interface com.exsamp.rem.MyRemote 








Class location (directory or JAR) 


[tendProjects WebService Sample\bulldWebServiceSample-classes'WEB-INFiclasses al 





os iter 


@ AllClasses ( Remote Classes (© Non-Remote Classes ( EJB Classes 














exte Cancel Help 


By default, this panel finds the compiled classes in the selected project’s build directory and lists 
them in the Available Classes box. For a WAR project, this list comes specifically from WEB- 
INF/classes in the build directory. 


> To select from the current list: 


1. Click an item in the Available Classes list. 
2. Click Next. 


> To refine the current list: 


e Click one of the Class Filter radio buttons to narrow the Available Classes list to classes 
of a particular kind. 
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> To list classes from another location: 


Click the browse (...) button for Class location (directory or JAR) to select a different 
directory or JAR file. 


This refreshes the Available Classes list to show just the compiled classes from that new 
location. 


WSDL file selection 


This panel is used to select a WSDL file from which the wizard is to generate Web Service files. 


You can select it from your project, from your file system, or from the Web (by specifying an 
URL). 


NOTE If you’re planning to generate a new Web Service from a WSDL file, you may need to 
edit that WSDL file beforehand to make sure the SOAP address in the service 
definition specifies the correct binding URL. The Web Service Wizard will use this 
URL in the files it generates for your Web Service. 


3% Web Service Wizard [x] 


Select the WSDL file or URL from which you would like 
to generate Web Services classes. 


WSDL Files In Project 





eSampleisrcicomiexs: 




















[CteXtendProjectstebServiceSampletsrcicomiexsampiwsdiMyS.wsd] TA | 








exte Cancel Help 


By default, this panel finds the .wsdl files in the selected project and lists them in the WSDL 
Files In Project box. 
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> To select from the current list: 


1. Click an item in the WSDL Files In Project list to make it the WSDL file to use. 
2. Click Next. 


> To select from the file system: 


1. Click the browse (...) button for WSDL file or URL to use to select a WSDL file from 
your file system. 


2. Click Next. 


> To specify a file by URL: 
1. Type the URL for the target WSDL file in WSDL file or URL to use. For example: 


http: //upload.eraserver.net/circle24/autoloan.asmx?wsdl 


2. Click Next. 





12 Panel details 


eXtend Workbench Tools Guide 





Multiple namespace mapping 


This panel is used when you’re generating from a WSDL file that uses multiple namespaces for 
the complex types in its XML schema. It lets you map each namespace to a separate Java 
package. 


NOTE The mappings on this panel are used only if the option Map complex XML types to 
Java types is checked on the next panel (Class-generation and SOAP options). 


The selected WSDL uses multiple namespaces to 
define its data types. Please specify a separate Java 
package for each namespace's types. 













Namespace Package 


http: #skats netiservices! [com.myco.myapp 
http: //skats net/servicesiiteralTypes com.myco nyapp literaltypes 








Cancel’ Help 


This panel lists the appropriate namespaces and fills in a default package name for each one. 
You can edit any or all of these package names. Just make sure you specify a unique package 
name for each namespace. 


> To edit the namespace-to-package mappings: 


1. Double-click any name in the Package column to edit it, then type the text you want. 
(You can’t edit the names in the Namespace column.) 


2. When you’re done editing package names, click Next. 
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EJB home interface selection 


This panel is used to select the home interface that corresponds to an EJB session bean class or 
remote interface you’ ve specified on the class selection panel. 


Your selection has been identified as an EJB-based 
class. Please select the EJB Home interface associated 
with this class. 


Available Classes (1) 


nterface com.exsamp.eib. SBMyEJBHome 








Class location (directory or JAR) - 


[CeXtendProjects WebSer viceSampleWVEB-INF Wib'MyEJB-client jar ase | 











Next> Cancel Help 


By default, this panel looks in the location of the EJB session bean class or remote interface to 
find home interfaces (compiled classes that extend javax.ejb-EJBHome). If there are any, it lists 
them in the Available Classes box. 


> To select from the current list: 


1. Click an item in the Available Classes list to make it the Selected Class. 
2. Click Next. 


> To list classes from another location: 


e Click the browse (...) button for Class location (directory or JAR) to select a different 
directory or JAR file. 


This refreshes the Available Classes list to show just the compiled classes from that new 
location. 
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EJB loo 


kup information 


This panel is used to specify information that the Web Service will need to do a JNDI lookup for 
a selected EJB session bean. (JNDI is the Java Naming and Directory Interface.) 


3% Web Service Wizard Eg 


Specify the deployed JNDI name to be used to lookup a 
reference to your Enterprise Java Bean. In addition, 
specify any application server-specific information 
necessary to create an Initial Context. 


M Deployed JHDI Name 





Lookup String [elbSBMyEVE 





M Initial Context Information - 





Factory Class [comssswertindiAgntCixFactory = 
Provider URL [sssw:MlocalhostWWebServiceSampleDB O 
User ID [administrator | 
Password [admin 














ack) Next > Gancel Help 


This panel displays default initial context values appropriate for looking up a session bean 


deployed to the SilverStream eXtend Application Server. For information on what other J2EE 
servers require, consult their documentation. 
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> To complete this panel: 


1. 


Specify the Deployed JNDI Name: 





Option 


What to do 





Lookup String 








Specify the subcontext and JNDI name under which the session 
bean is registered on the target J2EE server. For example, to look 
up the session bean whose JNDI name is SBMyEJB in the ejb 
subcontext: 


ejb/SBMyEJB 





The wizard includes this information in the ejb-ref declaration it generates within the 
deployment descriptor web.xml. To learn how it is used at runtime to do a JNDI lookup, 
see the getSessionBean() method of xxxDelegate.java (the delegate class generated for 


the tie servlet). 


Specify Initial Context Information: 





Option 


What to do 





Factory Class 


Specify the package prefix and name of an InitialContext factory 
class that’s appropriate for the target J2EE server. 

















Provider URL Specify the URL for the JNDI namespace of the target J2EE server. 

User ID Specify a valid user name that has authority to log on to the target 
J2EE server and access the session bean. 

Password Specify the password for User ID. 





The wizard includes this information in the servlet declaration it generates within the 
deployment descriptor web.xml. To learn how these values are used at runtime, see the 
getInitialContext() method of xxxDelegate.java. 


Click Next. 
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Method selection 


This panel is used to select the methods you want to expose when generating a Web Service 
from a JavaBean or other Java class. 


3% Web Service Wizard x} 


Select the methods you would like to expose in your new 
Web Service. 


~ Selected class — 





[com exsamp.obj.MyObject 
Available Methods (2) 


String getString() 
boolean setString(String) 








Selected Methods (1) 





String sayHello() 














Add All | Add | Remove | Remove All | 





<Back Next> Cancel Help 


This panel examines the selected class and lists its eligible methods in the Available Methods 
box. 


> To select methods to expose: 


1. Use the Add and Add All buttons to move one or more items from Available Methods to 
Selected Methods. 


If necessary, you can use Remove and Remove All to move one or more items back. 
2. Click Next. 
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Class-generation and SOAP options 


This panel is used to select the Web Service files to generate (including skeleton, tie, and stub 
classes) and to specify SOAP implementation details to encode in those files. There are two 


variations of this panel: 


e Ifyou start with a WSDL file, you'll see: 


3% Web Service Wizard Eg 


Specify the Web Service classes you would like to 
generate and any associated SOAP options. 





Generation Options 
|v Generate stubs 
[T Generate skeletons: @ Tie-based © Not tie-based 
[7 Generate jBroker Web 1.x compatible classes 
Directory with local XSD files: W 


[V Map complex XML types to Java types 


"Finish Cancel Help 
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Specify the Web Service classes you would like to 
generate and any associated SOAP options. 





; Generation Options 
[V Generate stubs 

[V Generate skeletons: @ Tie-based ( Not tie-based 
[V Generate WSDL file 

[T Generate jBroker Web 1.x compatible classes 


eR S y Þa — 


Target namespace: furn:com.exsamp.obj.MyObject 
Service address: [htte: ocainostVebSer viceSampleDBMNehServiceSample/MyObject 


Binding style: © Document style & literal encoding 








@ RPC style & SOAP encoding 














jack) Finish) Cancel Help 


Note that only this variation provides the SOAP options and the ability to generate a 
WSDL file. 


If you start with anything else (JavaBean, Java class, EJB session bean, or Java remote 
interface), you'll see: 


3% Web Service Wizard Eg 
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> To complete this panel: 


1. 


Specify Generation Options: 





Option 


What to do 





Generate stubs 


Check this option to generate classes for consuming the Web 
Service, including service classes, a stub class, and a simple client 
application. You’ll get the following source files: 


e xxxService.java 
e xxxServiceImpl java 
e xxx_Stub.java 


e xxxClient.java 





Generate 
skeletons 








Check this option to generate classes for implementing the Web 
Service. Then choose one of these implementation models: 


e Tie-based Generates skeleton and tie servlet classes used to 
handle requests for your Web Service and delegate method calls 
to a separate implementation class. You’ ll get the following 
source files: 


e xxx_ServiceSkeleton.java 
e xxx_ServiceTieSkeleton.java 
e xxxTie.java 


If you start with a JavaBean, Java class, or EJB session bean, 
you'll also get this source file (used to delegate to your class): 


e xxxDelegate.java 


e Not tie-based Generates just a skeleton servlet class used to 


handle requests for your Web Service. You’ll get the following 
source file: 


e xxx_ServiceSkeleton.java 
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Option 


What to do 





Generate WSDL 
file 


(If displayed) Check this option to generate the following file: 
e xxx.wsdl 


It describes your Web Service in standard WSDL format, which is 
useful when publishing to a registry. The wizard stores this file in 
the base directory of your source tree (commonly named sre). 





Generate 
jBroker Web 1.x 
compatible 
classes 


Check this option to generate the specified files according to the 
original jBroker Web (Version 1.x) conventions for: 


e File names 
° Stub access in client code 


Except for these conventions, the generated files will conform to 
the latest version of jBroker Web. 


This option is appropriate only if you’re maintaining an application 
that originated in jBroker Web 1.x and aren’t yet ready to switch to 
the current conventions (which are based on JAX-RPC and may 
require some changes to existing code). 


LL) For details on what this option generates, see the chapter on 
generating Web Services in the Development Guide. 





Directory with 
local XSD files 


(If displayed) When the selected WSDL file relies on imported 
XSD files for its type definitions, you can optionally specify a local 
directory that contains copies of them. If the wizard can’t access a 
particular XSD file based on the location specified in the WSDL 
file, it will look for that XSD file in your local directory. 


LJ For more information about XSD files, see the WSDL 
specification. 





Map complex 
XML types to 
Java types 








(If displayed) Check this option if the wizard should try to map 
complex types defined in the selected WSDL file (via XML 
Schema) to specific Java types. 


Uncheck this option if the wizard should map all complex XML 
types to the org.w3c.dom.Element Java type. 
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2. Specify SOAP Options (if displayed): 








Option What to do 
Target Specify the target namespace for SOAP messages produced by the 
namespace generated stub and skeleton classes. Method and parameter names 


are scoped to this namespace when SOAP messages go over the 
wire. 


You can accept the default value or specify any string for the 
namespace. It doesn’t have any special semantics beyond 
providing a scope for SOAP messages. 


When generating a WSDL file, the wizard uses this value for the 
targetNamespace definition. 





Service address 








Specify the URL to be used as the binding for accessing your Web 
Service. The wizard includes this binding information in the 
following generated files: 


¢ The stub class (xxx_Stub.java) and service implementation 
class (xxxServiceImpl.java) use it as the default URL for 
binding to the Web Service. 


¢ The WSDL file (xxx.wsdl) uses it as the SOAP address in the 
service definition. 


The default value for this option includes the name of the selected 
WAR project and the servlet mapping for the Web Service. For 
example: 


http: //localhost/WebServiceSample/MyObject 


If you plan to deploy the Web Service to the SilverStream eXtend 
Application Server, you need to insert the name of the target 
database in the URL: 


http: //localhost /WebServiceSampleDB/WebServiceSample/ 
MyObject 
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3. 





Option 


What to do 





Binding style 








Choose one of the following: 


e Document style & literal encoding In this format, the SOAP 
message body contains just the XML document being 
exchanged and message parts map to elements literally defined 
in the WSDL file's XML schema 


e RPC style & SOAP encoding In this format, the SOAP 
message body contains argument and return values, individually 
wrapped in ad hoc elements that the recipient must interpret by 
applying specified encoding rules to each message part's type 


When making this choice, consider the requirements of any other 
Web Service environments your Web Service must interoperate 
with. In most cases either style should work, but some 
environments may favor a particular style. 








Click Finish. 





Panel details 


23 


5 Web Service Wizard 








24 


Panel details 





Source Editors 





Workbench provides two sets of editors, one set based on open-source NetBeans editors and the 
other set native to Workbench: 
e NetBeans-based editors 
e Java Editor 
e JSP Editor 
¢ HTML Editor 
e XML-related editors 
e Native editors 
e Text Editor 


e Text views of the Deployment Descriptor Editor, Deployment Plan Editor, and WSDL 
Editor 


e Non-default versions of the Java, JSP, and HTML editors 
This chapter describes the basic functionality of these editors: 
e Common features 


e The NetBeans-based editors 


e The native editors 


Specialized features Other chapters in this guide cover the specialized features of the 
following editors: 

e Chapter 7, “XML Editors” 

e Chapter 8, “WSDL Editor” 

e Chapter 10, “Deployment Descriptor Editor” 

e Chapter 11, “Deployment Plan Editor” 
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Common features 


This section describes features common to all Workbench editors. 


Standard editing features 
Editor preferences 
Searching across multiple files 


Using text abbreviations 


Changing case 


Changing spaces, tabs, and indentation 


Standard editing features 


All Workbench editors provide these text-editing features: 





To perform this function 


Use this menu item 





Cut, copy, and paste 


Under Edit: 

e Cut (or Ctrl+X) 

e Copy (or Ctrl+C) 
e Paste (or Ctrl+V) 





Undo and redo 


Under Edit: 
e Undo (or Ctrl+Z) 
e Redo (or Ctrl+Y) 





Select all text 


Under Edit: 
e Select All (or Ctrl+A) 








Toggle the display of line 
numbers 





Under View: 
e Line Numbers (or Ctrl+L) 











Common features 


eXtend Workbench Tools Guide 








To perform this function Use this menu item 





Find and replace Under Search: 

e Find (or Ctrl+F) 

e Find Next (or F3) 

e Replace (or Ctrl+R) 


NOTE You can also search across multiple files. See 
“Searching across multiple files” on page 3. 


NOTE The native editors provide support for regular 
expression search. See Regular Expressions for 
Text Searches in the Reference. 





Moving cursor to a line Under Edit: 


e Go To Line (or Ctrl+G) 














Editor preferences 


Much of the editor display and behavior can be configured in the Text Editing tab on the 
Preferences dialog, which you can access using Edit>Preferences. This tab contains settings 
such as font size displayed in the editors, spaces per tab character, whether to show line 
numbers, and so on. 


LL) For details, see “Text editing preferences” on page 16. 


Searching across multiple files 


You can search across multiple files at once. You can search through: 


e All files that are open in Workbench 
e Files that are in all open projects 
e Files in a specified open project 


e Specified files on the file system 
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> To search across multiple files: 


1. Select Search>Find in Files or press Ctrl+Shift+F. 
The multiple-search Find dialog displays. 


NOTE You can also access the multiple-search feature from the standard Find dialog in 
the native editors by clicking the Find in Files button. 


2. Specify the following: 























Field Description 

Search for The text to search for. You can select previously searched text. 

Search in The set of files you want to search through 

Direction Whether to search forward or backward 

Match case Whether the found text must match the case of the search text 

Match whole word Whether the found text must be complete words 

Regular expression Regular expression to search for. For details, see Regular 
Expressions for Text Searches in the Reference. 














3. Click OK. 


Workbench searches through the specified files. All lines of text containing matching text 
are listed in the Find tab of the Output Pane. 


4. To display the found text, double-click the line of text in the Output Pane. You can view 
each instance of found text in its corresponding source file: 


e Select Search>Next Occurrence (or press F4) 
e Select Search>Previous Occurrence (or press Shift+F4) 


Using text abbreviations 


You can define abbreviations that can be expanded to one or more lines of text. For example, 
you can specify that a word can expand to a predefined language construct. For example, the 
abbreviation main might be defined to expand to this code in a Java file: 


public static void main(String args[] ) 


{ 
} 
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The abbreviations defined in Workbench appear on the Abbreviations tab of the Preferences 
dialog (Edit>Preferences). From this dialog you can define new abbreviations and change or 
delete existing abbreviations. For details, see “Abbreviations preferences” on page 19. 


Once you have defined an abbreviation, you can replace its name with the associated expanded 
text using Edit>Text Tools>Complete Abbreviation (or by pressing Ctrl+U). 


Changing case 


You can easily change the case of text. 





To perform this function Use this menu item 





containing insertion point 








Changing case of word Under Edit>Text Tools: 
e To Uppercase 


e To Lowercase 








Changing spaces, tabs, and indentation 


You can change how the native editors use spaces, tabs, and indentation using the menu items 








under Edit>Text Tools. 
To make this change in your text file Do this 
To change spaces to tabs or tabs to spaces Under Edit>Text Tools: 








e Spaces to Tabs 
e Tabs to Spaces 


If you select text before choosing these 
menu items, only that text is affected; if 
nothing is selected, the entire file is affected 
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To make this change in your text file Do this 





To remove trailing whitespace Under Edit>Text Tools: 
e Remove Trailing Whitespace 


If nothing is selected, this action works on 
the current line; otherwise it acts on all 
selected lines 








To change the indentation level Under Edit>Text Tools: 
e Shift Right 
e Shift Left 


You must select text on at least one line 
before you can select either of these menu 
items 











The NetBeans-based editors 


The core Workbench editors are based on NetBeans, an open-source Java-based framework and 
set of editors. The core Workbench editors are: 


Java Editor 
JSP Editor 
HTML Editor 


XML-related editors (the XML-related editors have different features than the other 
NetBeans-based editors and are described in Chapter 7, “XML Editors”) 


NOTE Previous releases of Workbench used native versions of the Java, JSP, and HTML 


editors. The native versions are still provided with Workbench, and you can configure 
Workbench to use them instead of the NetBeans versions. See “Using the native Java, 
JSP, or HTML editor” on page 15. 


The following sections describe the NetBeans-based editors. 


Color coding 

Code completion 

Adding files types edited by NetBeans-based editors 
Other editing support 
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Color coding 


The NetBeans-based Java, JSP, and HTML editors color-code syntactic elements to make it easy 


for you to read your code. 


The Java Editor uses special colors for these elements: 





























Syntactic element Color 

Java keyword Blue 
Method call Bold black 
String literal Red 
Numeric literal Gray 
Matching brace Magenta 
Comment Green italics 





The HTML Editor uses colors for these elements: 
































Syntactic element Color 

Tag Blue 

Tag attribute Green 
Attribute value Red 
Character reference Red 

SGML declaration Orange 
Matching brace Magenta 
Comment Gray italics 
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The JSP Editor uses the same colors for Java components as the Java Editor and the same colors 
for HTML components as the HTML Editor, plus: 























Syntactic element Color 

Block of Java Orange background 

JSP tag/directive Bold blue with gray background 
JSP tag attribute Green 

JSP tag attribute value Magenta 

JSP comment Bold gray 











Code completion 


As you are coding your Java in the Java Editor (or coding Java in a JSP page using the JSP 
Editor), you can use the Workbench’s code completion feature. As you type, you can display a 
list of possible classes, methods, variables, and so on that can be used to complete the Java 
expression. 


The elements displayed in the Java code completion box are defined by Workbench parser 
database files. Workbench ships with predefined parser files that include the following classes: 


J2EE 1.2 
JDK 1.3 
Servlet 2.3 


xalan and xerces (the versions that ship with Workbench) 
Ant (the version that ships with Workbench) 
jBroker Web (the version that ships with Workbench) 


You can create your own parser database files to make your own classes available for code 
completion. For details, see “Creating parser database files” on page 10. 
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> To complete a Java expression: 


1. In the Java Editor or in a block of Java code in the JSP Editor, type the first few characters 
of the expression, such as: 


String srcname; 


srcname. 


2. Press Ctrl+Space or Ctrl+\, or pause after typing a period, a comma, or the keyword new 
or import (followed by a space). 


The code completion box is displayed, providing a scrolling list of possible classes, 


methods, variables, 


and so on that can complete your expression. 


3 
E 


public String getSQL (javax.servlet.http.HttpServletRequest req, String sql 


{ 


String result; 
String srcename; 
srconame. 





AgiHt {java lang String.* 


y char charAttint index) 


name 7 Object cloned throws CloneNotSupportedException 
srcnal int compareTo(Object o) 


try { 


int compareTo¢String anotherString) 
int compareTolgnoreCase(String str) 
String concat(String str) 

String copyValueOf(char] data) 


out. pr] String copyValueOfi(char] _ int offset, int count) 


javax 


f Source 








boolean endsWith(String 


In the preceding screen shot, the box lists methods and fields available for strings. 


For methods and fields, the code completion box displays only static or only nonstatic 
options, depending on the context of your code. The options are color-coded: 


e Classes, methods, and exceptions are red 


e Arguments are magenta 


e Interfaces are gray 


e Fields are blue 
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3. While the code completion box is displayed, you can do the following: 





Do this In order to 





Continue to type Dynamically update the list of items in the code 
completion box based on your current entry 





Select an item and press Enter Insert an item into your code and close the code 
completion box 








Select an item and press Insert an item into your code and keep the code 
Shift+Enter completion box open 
Press Tab Insert into your code the letters that are common to 


all the items in the list and keep the box open 





Press Escape Close the box without inserting anything 














Inserting methods If you select a method with arguments, the method is inserted with 
replacement text for the first argument. If you specify that argument and type a comma, the 
completion box opens again so you can insert in the next argument, and so on. 


Workbench displays the data type of the entered arguments in the title of the code completion 
box; it displays a question mark if it can’t recognize the type. If you enter an argument that does 
not match any of the recognized argument lists for the method name, all the recognized methods 
are displayed (along with their argument list), and an asterisk (*) appears for the unrecognized 
argument(s) in the title of the code completion box. 


Creating parser database files 


The items displayed in the code completion box are defined by the Workbench parser database 
files. You can have Workbench create database files of your own classes so that they are listed 
in the code completion box when appropriate. 


> To create the parser database files: 
Open a project. 

Build the project. 

Select Edit>Preferences. 


Pee RS 


Select the NetBeans Directories tab. 
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8. 


To add your parser files to the same database (directory) as the predefined files, select the 
directory in the Java Completion Directories box. To put the files in a different database 
(directory), click Add, specify the directory, and select it. 


Click Create. 
The Update Parser Databases dialog displays. 


Specify the following information: 











Setting Description 

Parser database file prefix The names of the parser files that will be created. 
Workbench will create two files: prefix.jcb and 
prefix.jcs. 

Java source file directory The root of the directory containing your project’s 


source files, such as c:\myProject\sre 





Classes, Methods, and Fields | The visibility of the objects you want to include in 
the database 














Click OK to add the files to the parser database. 


If you later make changes to your project and want the changes to be reflected in the code 
completion lists, you must recreate the parser database files. 


Adding files types edited by NetBeans-based editors 


By default, Workbench is configured to edit java, .jsp, and .html files with the NetBeans-based 
editors. You can specify additional file types to edit with these editors. For example, you might 
have .htm files that you want to edit with the NetBeans-based HTML Editor. You would add 
-htm as a file type for the HTML Editor. 


> To edit additional file types with NetBeans-based editors: 


1. 
2. 


Select Edit>Preferences. 
Select the Editor Setup tab. 


This tab lists the NetBeans kits that are installed and allows you to specify which you want 
to use. 


The list at the bottom of the tab maps file extensions to a NetBeans kit. 
To add a file type, click Add. 
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4. Specify the file extension (wild cards are not supported) and the appropriate NetBeans 
editor kit. 


5. Click OK. 


The additional file type is listed in the Extension mappings table. When you open a file 
with the specified extension, it will open in the associated NetBeans-based editor. 


NOTE You can also specify that you do not want to use a NetBeans-based editor to edit .java, 
jsp, or .html files, in which case Workbench will use the corresponding native editor. 
For details, see “Using the native Java, JSP, or HTML editor” on page 15. 


Other editing support 


The NetBeans-based editors also provide the following special editing features. 


Navigating and selecting text 

















Keys Description 

Alt+Shift+T Moves the insertion point to the top of the window 
Alt+Shift+M Moves the insertion point to the middle of the window 
Alt+Shift+B Moves the insertion point to the bottom of the window 
Alt+J Selects the word the insertion point is on, or deselects any 


selected text 








Ctrl+Up Arrow Scrolls the window up without moving the insertion point 
Ctrl+Down Arrow Scrolls the window down without moving the insertion 
point 
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Deleting text 




















Keys Description 

Ctrl+E Deletes the current line 

Ctrl+H Deletes the character preceding the insertion point 

Ctrl+W Deletes the current word or the word preceding the insertion 
point 








Searching for text 























Keys Description 

Ctrl+F3 Searches for the word the insertion point is in and highlights all 
occurrences of that word 

F3 Moves the insertion point to the next occurrence of the found 
word 

Shift+F3 Moves the insertion point to the previous occurrence of the 
found word 

Alt+Shift+H Toggles highlighting of words 








Changing indentation 

















Keys Description 
Ctrl+T Shifts text in line containing the insertion point to the right 
Ctrl+D Shifts text in line containing the insertion point to the left 
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The native editors 











Bookmarks 
Keys Description 
Ctrl+F2 Sets or unsets a bookmark at current line 
F2 Goes to next bookmark 














The core Workbench editors are based on NetBeans and have the features described above. The 
following editors are native to Workbench and have a different feature set: 


Text Editor 


Text views of the Deployment Descriptor Editor, Deployment Plan Editor, and WSDL 


Editor 


Non-default versions of the Java, JSP, and HTML editors 


The following sections describe the native editors. 


Changing line ending characters 


Multiple clipboard support 


Viewing and changing read-only and read-write attributes 
Using the native Java, JSP, or HTML editor 


Inserting custom tags in a JSP page 


Changing line ending characters 


You can convert all DOS-style line ending characters to UNIX-style line ending characters by 
selecting Edit>Text Tools>Convert to UNIX Line Endings. To convert all UNIX-style line 
endings to DOS-style endings, select Convert to DOS Line Endings. 


NOTE Changing line endings causes no visual change in the editor. 
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Multiple clipboard support 


You can copy or move multiple instances of text. The editor keeps track of your most recently 
used clipboards. Copying and cutting multiple times creates a clipboard with multiple listings. 
When you press Control+Shift+V, the editor lets you select which text to paste. 


Viewing and changing read-only and read-write attributes 


When you open a file in a native editor, Workbench displays in the bottom-right corner whether 
the file has read-only (RO) or read-write (RW) permission. If a file is in RO mode, you cannot 
make changes to it in the editor. You can switch between RO and RW mode by clicking on this 
indicator. 


Switching from RO to RW mode enables you to make changes in the editor. However, the 
ability to write to the file (for example, using File>Save) is still controlled by the file system 
permissions for that file. You cannot save changes to a file unless the file is marked writable by 
the file system. 


Using the native Java, JSP, or HTML editor 


By default, Workbench uses NetBeans-based Java, JSP, and HTML editors (see “The NetBeans- 
based editors” on page 6). If you want, you can use the native versions of these editors in order 
to get the functionality described above for the native editors (plus, with the native JSP Editor, 
you can use the Custom Tag Wizard; see “Inserting custom tags in a JSP page” on page 16). 


> To use the native Java, JSP, or HTML editors: 


1. Select Edit>Preferences. 
2. Select the Editor Setup tab. 


This tab lists the NetBeans kits that are installed and allows you to specify which you want 
to use. 


The list at the bottom of the tab maps file extensions to a NetBeans kit. 


3. If you do not want to use the NetBeans-based editor for a file type (and instead use the 
native editor), select the file type in the Extension mapping table and click Remove. 


4. Click OK to confirm. 


File types no longer in the list will use the corresponding native editor, providing the features 
described for the native editors. 
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Inserting custom tags in a JSP page 


In JSP pages, custom tags enable you to extend the functionality provided by standard JSP tags, 
either by writing your own tag library or by using a tag library provided by a third party, such as 
the Jakarta project. Tag libraries consist of the Java classes that provide functionality for the tags 
and a tag library descriptor file, an XML document that describes the tag library. 


You import a tag library into a JSP page using a taglib directive that specifies the location of the 
tag library descriptor file and declares an identifier that you can use as a prefix to reference the 
various tags in that library. For example: 

<%@ taglib uri="/WEB-INF/tlds/app.tld" prefix="apptags" %> 


references a tag library called app.tld, located in the /WEB-INF/tlds directory in the archive. 
You can refer to tags in the library using the apptags prefix. For example, if the tag library 
contains a tag called AskUserName, you could create an instance of that tag in the JSP page 
using this line: 


<apptags :AskUserName></apptags :AskUserName> 


The Custom Tag Wizard 


The native Workbench JSP Editor provides a Custom Tag Wizard that enables you to easily 
insert custom tags into a JSP page. 


> To insert JSP custom tags using the Custom Tag Wizard: 


1. Create the classes and descriptor files for your tag library. 


2. Add the classes and descriptor files to your Workbench project. A typical location for 
class files is a WEB-INF/classes directory; for descriptor files, it is typically WEB- 
INF/tlds. 

3. Edit the JSP file in which you want to use the custom tags, adding a taglib directive to 
import the tag library. 


4. Position the cursor at the point in the JSP file where you want to insert a custom tag. 
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5. Select Edit>Insert Custom Tag>Custom Tag Wizard. 


NOTE You must be using the native JSP Editor to access this wizard. See “Using the 
native Java, JSP, or HTML editor” on page 15). 


If the page has more than one taglib directive, a list of all tag libraries specified on the 
page displays. For example: 


Select a Custom Tag Library 


CustomTags --> Custom 
SampleTags --> Sample 





Jext Cancel Help 


Select the tag library you want to use and click Next. 
6. If Workbench cannot find the tag library specified, it prompts you to locate it on your file 
system. 


7. Once you have specified the tag library, a list of all tags contained in that library displays. 
For example: 


Select a Custom Tag 


SimpleTag 
AttributeTag 
SimpleBodyTag 





ish Cancel Help 
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8. Select the tag you want to insert and click Finish. The custom tag code appears in the JSP 
file. For example: 








C:WYorkbenchProjects mple\jspstest jsp* 





He 


<html> 
<jsp:useBean id="clock" scope="page" class="util.JspCalendar"/> 
<jsp:useBean id="sql" scope="request" class="util.JspSQL"/> 


<%@ taglib uri="SampleTags” prefix="Sample” $> 
<$@ taglib uri="CustomTags” prefix="Custom™ $> 


<h4>Use a tag library</h4> 
<Sample:AttributeTag message=""></Sample: AttributeTag> 


<h4>Use the implicit Request object</h4> 

<ul> 

<li>Server name: <%= requ -getServerName() $> 
<li>Server port: <%= requ -getServerPort() $> 
<li>HTTP method: <%= request.getMethod() $> 
</ul> 





<h4>Use a Bean to access date information</h4> 


<ul> ha 
Kil Fa 


Í E Source 














In this example, the following lines were added manually in Step 3: 

<%@ taglib uri="SampleTags" prefix="Sample" %> 

<%@ taglib uri="CustomTags" prefix="Custom" %> 

The wizard added this line to instantiate the custom tag: 

<Sample:AttributeTag message=""></Sample:AttributeTag> 

9. If necessary, modify the code inserted by the wizard to complete the tag specification. For 

example, in the tag in the preceding example you would specify a value for the message 

attribute. 
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This chapter describes the facilities that Workbench provides to work with XML and XML- 
related files. It contains the following topics: 

e About XML 

e XML support in Workbench 

e Using the XML Editor 

e Creating and opening XML documents 

e Associating Schemas and DTDs with XML documents 
e Converting a DTD to a Schema 

e Editing an XML document 

e Using the Schema Guide 

e Validating an XML document 

e Searching an XML document 

e Maintaining the XML catalog 

e Using the XSL Editor 

e Keyboard shortcuts 


About XML 


XML (Extensible Markup Language) is a language designed to facilitate the exchange of data 
between computer systems (which can be of different types) and applications on the Web. XML 
is a project of the World Wide Web Consortium (W3C). It is a standard, public format. 


Unlike HTML, XML is extensible. It is a metalanguage, a language that describes other 
languages. With XML, you can define customized markup languages to describe any type of 
document structure. XML can be used to specify the structure of anything from a recipe (which 
might consist of descriptions, ingredients, preparation steps, and so on) to a Web application 
(WAR deployment descriptors are XML documents). 


The definition of an XML document is specified by either a Document Type Definition (DTD) 
or a Schema. DTDs, which are older, specify the structure of an XML document. They specify 
the names of elements, attributes, and entities that can exist in a conforming XML document. 
DTDs also specify where the elements can be used, whether they are required, and so on. 
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Schemas are more recent and more powerful. They can specify the structure as well as the 
content (data types) allowed in XML documents. Unlike DTDs, Schemas are themselves XML 
documents. 


LL) The complete XML standard can be found at http:/www.w3.org/XML. 


TIP Ifyou are new to XML, you might want to read the XML FAQ at http://www.ucc.ie/xml. 
Among other topics, it describes the differences between Schemas and DTDs. 


XML support in Workbench 


Workbench provides comprehensive support for working with XML files, including: 


e XML-related wizards: 

e XML Wizard to create an XML file 

e XML Catalog Wizard to create a catalog entry file 

e DTD to Schema Wizard to convert a DTD to an XML Schema 
e XML-related editors: 

e XML Editor 

e XML Catalog Editor 

e XSL Editor 


This chapter describes these XML facilities. 


Using the XML Editor 
The XML Editor lets you: 


e View and edit XML documents in a syntax-colored Source View or a Tree View 


e Easily create and modify document elements through the editor’s context-based code 
completion and the Schema Guide window 


e Attach a Schema or DTD to an XML document 

e Detach a Schema or DTD 

e Validate an XML document against a Schema or DTD 
e Convert a DTD to a Schema 
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Using the Source View 


The Source View provides you with a powerful XML source editor. In addition to standard text 
editing features—including cut-and-paste editing, undo and redo, and searching and replacing 
text—it supports these specialized features for editing XML files: 

e Context-sensitive code completion (see “Editing an XML document” on page 11) 


e Formatting of XML elements (see “Modifying text” on page 35 and “Changing 
indentation” on page 37) 


e Navigating by XML elements (see “Moving the insertion point” on page 33) 

e Finding matching tags (see “Moving the insertion point” on page 33) 

e Bookmarks (see “Bookmarks” on page 37) 

e Specifying colors to display different types of information (see “XML Editor color 


preferences” on page 24) 


The XML Editor displays the current XML document in the Source View if you click the XML 
Source View tab. 








C:WVvorkbenchProjects\Sandbox'personal.xml (using: personal.xsd) 


> & 


<?xml version="1.0" encoding="UTF-8" 2> 
<personnel xmlns ="http: Š .org D 1 MLSchema-instance'’ 
x31: noNamespaceSchemaLocation='personal.xsd'> 


<person id= J. > 
<name><family>Boss</family> <given>Big</given></name> 
<email>chief@foo. com</email> 
<link subordinates= . r two. t + Wor four. work 
<f/person> 


<person id= > 
<name><fanily>Worker</family> <given>One</given></name> 
<email>onelfoo. com</email> 
<url href="http: - worker. i> 





<link manager="Big.Boss"/> | 
al | » 
© XML Source View [4 XML Tree View 





Using the Tree View 
The Tree View has special features designed to help you create valid XML documents quickly 
and easily based on XML Schemas or DTDs. The Tree View supports: 
e Context-sensitive editing (see “Editing an XML document” on page 11) 
e Cut-and-paste editing (see “Editing objects” on page 16) 
e Drag and drop (see “Editing objects” on page 16) 
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e Searching by name, value, or XPath (see “Searching an XML document” on page 23) 
e Finding matching elements (see “Navigation and display” on page 30) 


The XML Editor displays the current XML document in the Tree View if you click the XML 
Tree View tab. 








kbenchProjects'Sandbox'personal.xml (using: personal.xsd) 


> & 


Di Document 











i$; personnel 










personal.xsd 


y: http: JAwwwy w3.org/20004 07X1 


E- ig person 


E i$ person 


H- ig name 


E i$ email 
=) one@too.com al 
X 
4 m 
E ei url 
E ei link 





= XML Source View| <b, XML Tree View 








NOTE The Tree View does not show or manipulate XML comments. 


Tree View display buttons 











Icon Description 

Expand element list (show subelements as well as the text value and 
CDATA for the element) 

E Collapse element list 





rai Display menu allowing you to toggle the display of all elements’ 
iji attributes and namespace declarations 





Display menu allowing you to show or hide an element’s attributes and 
namespace declarations 
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Tree View icons 














Icon Description 
at Document 
Element 





Text value of an element (for example, the text value of <myTag>the 
text</myTag> is the text) 








CDATA 








Attribute 





Required attribute 








Namespace declaration 





Search result 











Indicates that the XML cannot be parsed 








Creating and opening XML documents 


You can create new XML documents or work with existing ones. 


> To create a new XML document: 


1. Select File> New. 
2. On the XML tab, select XML file. 
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3. To create a blank XML document, deselect Use Wizard and click OK. An empty XML 
document is created and displayed in the XML Editor. 


To use the XML Wizard, select Use Wizard and click OK. The XML Wizard displays. Go 
through the wizard as follows. 


4. Specify the name and location of the XML file and click Next. 
5. Specify a Schema or DTD to associate with the XML file. You can: 


e Select a Schema URI from the list of Schemas in the Workbench catalog; the 
corresponding file name is displayed in the File Name field 


e Select a public or system identifier from the list of DTDs in the Workbench catalog; the 
corresponding file name is displayed in the File Name field 


e Select a Schema or DTD directly from the file system by clicking Browse and 
selecting the file 
C For more information about the Workbench catalog, see “Maintaining the XML 
catalog” on page 24. 
6. Click Finish. 
The XML Editor displays the Schema Guide. 
7. You can use the Schema Guide, or click Close to edit the file manually. 


LL) For information about the Schema Guide, see “Using the Schema Guide” on page 16. 


> To open an XML document: 


1. Select File>Open. 

2. Inthe Open dialog, select the XML file and click Open. 
The file extension must be .XML, .XSD (for a Schema file), or .TLD (for a tag library 
descriptor file). 
The file opens in the XML Editor. If you opened an .XML or .TLD file, there is a new 
XML Editor item on the menu bar. 


NOTE An XML file might instead be opened by a specialized XML editor, such as the 
XML Catalog Editor or Deployment Descriptor Editor. 


Finding Schemas and DTDs If the XML document specifies a Schema or DTD, 
Workbench searches for it when opening the document. If Workbench finds the Schema or 
DTD, it attaches it to the XML document. If the reference is unqualified, Workbench first looks 
in its XML catalog; if Workbench doesn’t find the Schema or DTD there, it looks in the 
directory containing the XML document. 


If the XML Editor cannot find the referenced Schema or DTD, you receive an error message in 
the Output Pane and the document is opened without being attached to the Schema or a DTD. 
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LL) For more information, see “Associating Schemas and DTDs with XML documents” on 





page 7. 
The window title for an XML document specifies whether the document is attached to a Schema 
or DTD. 
This XML document is 
attached to the 
personal.xsd Schema 
C:WorkbenchProjects\Sandbox\personal.xml (using: personal.xsd) 3 


iD; Document 

f=]. personnel 
E E person 
H it: person 


fo person 


Associating Schemas and DTDs with XML documents 


In order to use context-sensitive code completion and to validate your document, an XML 
Schema (.XSD file) or a DTD (.DTD file) must be attached to the document. 


If Workbench didn’t attach a Schema or DTD when opening an XML document, you can 
manually attach a Schema or DTD or modify your XML document to specify a Schema or DTD 


and refresh Workbench. 


Attaching a Schema or DTD to a document 


You can attach a Schema or DTD that is in the Workbench XML catalog or elsewhere on the file 
system to an open XML document. 


C For more information about the Workbench XML catalog, see “Maintaining the XML 
catalog” on page 24. 
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> To attach a Schema or DTD to an XML document: 
1. Select XML Editor>Attach Schema or DTD. 


3% Attach Schema or DTD x] 


Schema 


Schema URI : | X | 


DTD 
Public Identifier : | + | 
System Identifier : | + | 


Schema or DTD as File 


File Name : DT H 





ancel Browse... 


2. Specify a Schema or DTD to associate with the XML document. You can: 
e Select a Schema URI from the list of Schemas in the Workbench catalog; the 
corresponding file name is displayed in the File Name field 
e Select a public or system identifier from the list of DTDs in the Workbench catalog; the 
corresponding file name is displayed in the File Name field 
e Select a Schema or DTD directly from the file system by clicking Browse and 
selecting the file 
3. Click OK. 
The Schema or DTD is now attached to your XML document. You can use the XML 
Editor’s context support for editing, and you can validate your document. 


NOTE Attaching a Schema or DTD to an XML document is only for the purpose of context 
editing and validation in the XML Editor; it doesn’t modify the XML document itself. 
See the next section for permanently associating a Schema or DTD with the document. 


Errors Any errors that occur when attaching a Schema or DTD are reported in the Messages 
tab of the Output Pane. 
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Specifying a Schema or DTD in the XML document 


After opening an XML document, you might want to permanently associate the document with 
a Schema or DTD and make Workbench aware of the association. 


> To associate the document with a Schema or DTD and update 
Workbench: 
1. Edit the open XML document to specify the associated Schema or DTD. For example, to 
associate the document with a DTD, edit its DOCTYPE statement. 


2. Update Workbench to use the association by selecting XML Editor>Refresh Schema 
Handler. 


Workbench parses the XML document and updates the DTD or Schema information 
associated with the document. 


Errors Any errors that occur when updating the Schema or DTD information are reported in 
the Messages tab of the Output Pane. 


Detaching a Schema or DTD 


You can detach a Schema or DTD from an open XML document. 


> To detach a Schema or DTD: 


e Select XML Editor>Detach Schema or DTD. 


The Schema or DTD definition is no longer used by the XML Editor. Context editing and 
validation are no longer provided for the open document. 


The Schema or DTD is not permanently detached. The next time you open the XML document, 
if the document specifies a Schema or DTD that Workbench can find, the Schema or DTD will 
be attached again. 
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Converting a DTD to a Schema 


Schemas are more powerful than DTDs and are becoming the standard for defining the structure 
and allowable content type for XML documents. Also, unlike DTDs, Schemas are themselves 
XML documents and can be edited and validated in the XML Editor. 


If you have been using DTDs, you can use Workbench to convert a DTD to a Schema. You can: 


Convert a DTD on the file system to a Schema 


Convert the DTD attached to an open XML document to a Schema 


To convert a DTD on the file system to a Schema: 


Select File>New. 
On the XML tab, select DTD to Schema and click OK. 


Specify the DTD to convert. You can click the ellipses button to browse the file system for 
the DTD file. The file must have the extension .DTD. 


Specify the name of the Schema file to generate. Don’t provide a file extension; the file 
will be given the extension .XSD. 


Specify the location to save the Schema file. You can click the ellipses button to browse 
the file system. 


Specify whether you want the Schema opened in the XML Editor after it is created. 
Click Finish. 


Workbench converts the DTD to a Schema, stores the Schema in the specified location, 
and displays the Schema in the XML Editor if you specified to open it. 


To convert a DTD attached to an open document to a Schema: 


Attach a DTD to an open XML document. 
Select XML Editor>Convert DTD to Schema. 
A file save dialog displays. 


Specify the name and location of the Schema. Don’t provide a file extension; the file will 
be given the extension .XSD. 


Click Save. 


The Schema is saved. 


What to do next You can edit the generated Schema file in the XML Editor and attach it to 
an XML document for context editing and validation. If you want to permanently associate the 
Schema with an XML document, edit the XML document to specify the Schema. 
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Editing an XML document 


You can edit an XML document using either Tree View or Source View. If you have attached a 
Schema or DTD, you can use the XML Editor’s context support. 


About context support 


Workbench provides context editing in both the Tree View and the Source View. 


Context support in Tree View 


In Tree View, right-click at the appropriate location in the document. In the following 
illustration, a new person is being added to the document, and the XML Editor detects from the 
Schema that the next valid element is name. 


CW orkbenchProjects'\Sandbox'personal.ximl (using: C: WorkbenchProjects\Sandbox'ip... 29 


iD; Document 











= fi personnel 








t- igi person 


|i person 














Insert New Text 

Insert New CDATA 

Insert New Element Before... 

Insert New Text Before 

Insert New CDATA Before 

Insert New Attribute... » 
Insert New Namespace Declaration... 
Delete Node 

Delete Attribut > 














> 





Cut 

Copy 

Paste 
PasteAs Child 


> XML Source View Schema Guide 
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Once the name has been added, the XML Editor presents the new list of valid elements, 
according to the Schema. 







C:WorkbenchProjects'Sandbox'personal.xml (using: C:WYorkbenchProjects!Sandbox'p... 29 



























person 

















person 
Insert 


Insert New Text link 
Insert New CDATA url 
Insert New Element Before... > 
Insert New Text Before 

Insert New CDATA Before 









































































person 














Insert New Element... » 
Insert New Text 

Insert New CDATA 

Insert New Element Before... > 
Insert New Text Before 

Insert New CDATA Before 
































Insert New Namespace Declaration... id 
Delete Node note 
parte Attrindte > 











piee nemespace Decaretion b 
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Notice that the editor also provides the choice Other, allowing you to define an entry that does 
not conform to the Schema. If you choose Other, you see a dialog similar to the following: 


ZZ Insert New Element x] 


Warning: The new element might not be valid according to schema! 


Name: | 
Namespace: | z] 


L OK Cancel | 


Using the Schema Guide In addition to using the context menu to edit your XML 
document, you can use the Schema Guide for more comprehensive context support. See “Using 
the Schema Guide” on page 16. 







Context support in Source View 


In Source View, after you type < (to start an element tag) or a single space within an element (to 
define an attribute), the editor displays the valid entries (if there are any). For example: 





andbox\personal.xml (using: personal.xsd)* » 





C:WorkbenchProje 
<?xml version="1.0" encoding="UTF-8" ?> 
<personnel xuln; i="http: w3. Or 

xsi:noName 














chemaLocation='personal.xsd 





<person id="Big. > 
<name>Em< /name> 
< 
</personnésiement 


slink> 

surl> 

<person> 
4 


© XML Source View [a XML Tree View 
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Here a space has been typed in the url element, which results in a display of the valid attribute, 
href: 











C:WVorkbenchProjects'Sandbox'personal.xml (using: personal. xsd)* x 
<?xml version="1.0" encoding="UTF-8"?> 
<personnel xulns ="h - W3. 

xsi:noNamespaceïchemaLocation= aJi > 


<person id=" A > 
<name>Em< /name> 
<url > 


</personnel> |iiemen 
ma 


fA ee el | >l 


XML Source View 


4 








Adding elements 


> To add an element in Tree View: 


1. Select where you want to insert the element. 


2. Right-click and select Insert New Element to insert an element inside the current 
element, or select Insert New Element Before to insert an element before the current 
element at the same level. 

If valid elements can be inferred from the definition of the document, they will be listed. 
If no element can be inferred, you can add an element by choosing Other. You are warned 
that the new element might not be valid. 


> To add an element in Source View: 


1. Position the insertion point where you want to insert the element. 
2. Type <. 
If valid elements can be inferred from the definition of the document, they will be listed. 


If no element can be inferred, you can add an element by typing it. 
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Adding attributes 


> To add an attribute in Tree View: 


1. Select the element to contain the new attribute. 
2. Right-click and select Insert New Attribute. 


If valid attributes can be inferred from the definition of the document, they will be listed. 


If no attribute can be inferred, you can add an attribute by choosing Other. You are 
warned that the new attribute might not be valid. 


> To add an attribute in Source View: 


1. Position the insertion point inside an element where you want to insert the attribute. 


2. Type a space. 


If valid attributes can be inferred from the definition of the document, they will be listed. 


If no attribute can be inferred, you can add an attribute definition by typing it. 


Adding namespace declarations 


> To add a namespace declaration in Tree View: 
1. Select the element for the namespace declaration. 
2. Right-click and select Insert New Namespace Declaration. 
The Insert Namespace Declaration dialog displays. 


3. Specify the prefix, URL, and Schema location for the namespace. 
4. Click OK. 


> To add a namespace declaration in Source View: 


e Add the namespace declaration to the element definition. 
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Editing objects 


> To copy, move, or delete objects in Tree View: 
e You can use drag-and-drop to move objects, or use the right-mouse-button menu to 
perform the following actions: 


e Cut or Copy to place an object on the clipboard, then Paste to insert it before a selected 
object or Paste As Child to insert it as the last child of a selected object 


TIP Cut and Copy also place contents on the system clipboard, so you can paste a 
textual representation of the tree contents into other applications. Similarly, you 
can paste textual XML contents from other applications into Tree View. 


e Delete Node to delete an element and all its subelements 
e Delete Attribute to delete an attribute 
e Delete Namespace Declaration to delete a namespace declaration 


In all cases, you will be informed if the edit would result in an invalid document. You can 
choose whether to continue. 


> To copy, move, or delete objects in Source View: 


e Use the standard editing features, including cut and paste, in the editor. 


Reversing changes All editing actions can be undone by selecting Edit>Undo or pressing 
Ctrl+Z, or redone by selecting Edit>Redo or pressing Ctrl+Y. 


Using the Schema Guide 


The context editing functionality described above is very useful when editing XML documents, 
but doesn’t always provide all the information you might want. For example: 


e It doesn’t show exactly how a Schema (or DTD) is put together and what elements and 
attributes are allowable at different locations. 


e It doesn’t indicate whether an element must include a sequence of child elements before it 
is legal. For example, say element A must have elements B, C, and D as children to be 
valid. When you insert an instance of A, the standard context support described above 
suggests element B as a valid subelement. If B is inserted alone the document becomes 
invalid until you have inserted C and D. With the standard context support, you wouldn’t 
know this unless you perform a full validation of the document. 
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e Ifyou are looking for a specific element to insert, for instance D in the example above, 
with the standard context support you wouldn’t be informed about D unless you have 
inserted B and C first. 


e Ifan element contains illegal children, the standard context support doesn’t suggest new 
elements to insert, so you must perform a full validation to find out where the problem is 
and then correct it. 


The Schema Guide addresses these situations. 


> To invoke the Schema Guide: 
1. Select Tree View in the XML Editor or XML Catalog Editor. 


2. Do one of the following: 
e Right-click an element whose contents you want to edit and select Schema Guide. 
e Select an element and press Ctrl+Shift+G. 


The Schema Guide opens in a new window. 


The Schema Guide window 


3% Schema Guide Eg 


/personnel/person[2] 


Namespace URI: no namespace 








Content type : (<name>, <email>*, <url>*, <link>?) 





person 


one.worker 


<name> salary | 
<email> | 


name 
email 
url 
link 





<url> | 
<link> | contr | 


























x Guty Close 
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The Schema Guide window consists of four parts: 


e The top of the window displays the XPath for the selected element, its namespace, 
documentation for the element’s type (if any, taken from comments in the DTD or 
annotation elements in the Schema), and a textual DTD-like description of the element’s 
allowed contents 


LL) For more information about XPaths, see “XPaths” on page 22. 
e The left side contains a graphical representation of the definition of the selected element 


e The right side contains a tree representation of the actual instance of the selected element, 
including its attributes and children (but not its children’s children) 


e The bottom of the window contains wizard-style buttons 


In the screen shown above, the second person element (/personnel/person[2]) was selected 
when the Schema Guide was invoked. 


About the left pane 


The left pane shows the element’s subelements as well as the Schema model groups they belong 
to (Choice, Sequence, or All) or the model group declarations (for example, schemaTop). 


e Choice groups are shown with two elements on each row, with a horizontal bracket above 
and below 


e Sequence groups are shown with one element in each row and a vertical bracket on the left 
and right hand side of the contained elements 


e Attributes and All groups are displayed in boxes 


Positioning the mouse pointer over an element displays a tool tip describing the element if there 
is documentation for the element in the Schema or DTD. 


The Schema Guide also displays how many instances of each subelement and attribute are 
allowed. If exactly one of the subelement or attribute is required, no enumeration is shown. 
Otherwise, the Schema Guide displays the requirement (such as “0 or more”, “O or 1”, or “1 or 
more”). 


The Schema Guide is invoked automatically when you use the XML Wizard to create an XML 
document. You can also invoke it when the document is empty and has a Schema attached. In 
this situation, the Schema Guide lists in the left pane possible root elements. If using a DTD, the 
description in the header will show the suggested root elements (that is, those elements that are 
not in the content model of other elements). 
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About the right pane 


The right pane displays the standard Tree View of the XML Editor to show the element that was 
selected when the Schema Guide was invoked, its attributes, and its immediate children. 


Subelements that are not legal are shown with a red background. If the selected element contains 
an illegal attribute, the element itself is marked with red. Clicking on a colored element displays 
a similarly colored region of text along the bottom of the tree. The text describes the issue in 
more detail. 


In many cases, the Schema Guide can fix validation errors, either by removing illegal elements 
or attributes, or by moving an element from a wrong namespace into a correct one. In the 
following example, the Schema Guide is indicating that the age element is invalid in the person 
element. You can delete the invalid element by clicking Delete. 


3% Schema Guide x| 


/personnel/person[2] 


Namespace URI: no namespace 
Content type : (<name>, <email>*, <url>*, <link>?) 














quence attribut j 
| one.worker 
<name> | salary | | 
1 name 
<e mail> | 
0 or mor note | 


| 
<link> | contr | | 
Oor1 { 1 | 






email 
url 
link 























Changs Delete =- Close 





Namespace errors are treated separately. These errors are common when dealing with Schemas, 
because Schemas can contain elements from several namespaces and have different rules for 
whether specific elements or attributes are required to be in a namespace. An element that has 
the correct local name for the document to validate correctly but whose namespace is incorrect 
is shown with a yellow background. You can use the Change button to move the element to the 
correct namespace. 
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Adding elements and attributes 


Elements When selecting an element in the left pane, the tree view shows where the element 
can be legally inserted by displaying one or more green nodes in the tree. The following screen 
shows that an email element can be legally inserted above or below the existing email element. 


3% Schema Guide x| 


/personnel/person[2] 


Namespace URI: no namespace 
Content type : (<name>, <email>*, <url>*, <link>?) 





<name> | salary | 
| <email> 


one.worker 


name 
email 
email 


<url> | 5 email 





| i url 
[sinke | || Loont] i ink 











element <email> can be legally inserted at this location in the 











Ganga Usisis << Sack Guiv Close 





To insert an element, select one of the green elements in the tree and click Insert. If you don’t 
want to insert the element, simply select another object in the left pane to consider. 


If you click an element in the left pane that cannot be legally inserted, you will not see any green 


entries in the right pane. 


Attributes To add an attribute, select it in the left pane. If it is legal to add, you will see a 
green attribute in the right pane. Specify the attribute’s value and click Insert. 


Looking at different elements 


You can navigate the element hierarchy by selecting a subelement in the right pane and clicking 
Go to. The subelement becomes the selected element and its definition is now shown in the left 
pane and the tree structure for the selected instance is shown in the right pane. You can work 
with it the same way you worked with the parent element. 
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The following screen shows the Schema Guide after the person element’s name subelement was 
selected and Go to was clicked. 


/personnel/person[2]/name 


Namespace URI: no namespace 


Content type : (<family> « <given>) 








<family> | | 
| 
<given> | | 

| 


+ name 


į family 





given 














ss Ging Dslsis <<Back Guiy Close 


Click Back to return to working with the parent element. 


Validating an XML document 


As you type in Source View, the editor automatically highlights in red any areas of the document 
that are not well formed. The Tree View creates well-formed documents by design. 


You can also manually validate the document for conformance to the Schema or DTD. 


> To validate an XML document: 


e Select XML Editor> Validate to validate an XML document. 


NOTE The menu item is enabled only if the XML document is attached to a Schema or 
DTD. 
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The editor validates the XML document against the attached Schema or DTD. 








C:WVorkbenchProjects'Sandbox'personal.xml (using: personal.xsd)* 


> & 


<?xml version="1.0" encoding="UTF-8" ?> 
<personnel xmln tI wW. WS 























<person> 
<name><family>Boss</family> <given>Big</given></name> 
<email>chief@foo. com</email> 

</person> 


<person> 
<name><fanily>Worker</family> <given>One</given></name> 
<email>oneffoo. com</email> 
<url href="http: ne.worker. /> 

<f/person> 


je se ee | 
© XML Source View |an XML Tree View 








Validating personal: a 
2 error(s) 

[/personnel/person[1l]] The attribute Qid is required but is missing 
[/personnel/person[2]] The attribute Qid is required but is missing 





q z Build gf} validate 


The results The report identifying any malformed statements displays in the Validate tab of 
the Output Pane. 


XPaths References to errors are reported as XPaths. XPath (XML Path Language) is the 
W3C-endorsed language for addressing parts of an XML document. It uses a path notation 
similar to an URL for navigating through the structure of the document. (For more information, 
see http://www.w3c.org/TR/xpath.) 


For example, the XPath /personnel/person[1] indicates the first instance of person in the XML 
document, the XPath /personnel/person[2] indicates the second instance of person, and so on. 


In the preceding example, the id attribute is reported as missing from the first two person 
elements. 


TIP You can search for specific XPaths in Tree View. See “Searching an XML document’ on 
page 23. 
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Searching an XML document 


You can search your document in either Source View or Tree View. 


> To search an XML document: 


1. 


4. 


In either Source View or Tree View, select Search>Find or press Ctrl+F. 

The Find dialog displays. 

In Source View, you can perform standard text searches. In Tree View, you can specify the 
following: 

e Element names 

e Attribute names and/or values (see “Searching for attributes in Tree View” on page 23) 
e XPaths (see “XPaths” on page 22) 


Search for: 


Elements named: [ X | 


Attributes with: Name: Value: 








XPath: | a | 


Direction: 
@ Forward 
C Backward 
IV Highlight ALL found instances 


[V Wrap search 


OK Cancel Help 





Click OK to search. 

If there is a match, the first match is selected and all matching occurrences are indicated: 

e In Source View, matches are highlighted 

e In Tree View, elements containing the found text are indicated with the Search Result 
icon (*%) 


To go to the next occurrence, press F3. 


Searching for attributes in Tree View When searching for attributes, you can specify: 


Attribute name only—This will find all attributes of that name, in any element 


Attribute value only—This will find all attributes having the specified value, regardless of 
the attribute name 


Attribute name and value—This will find all attributes with the given name and value 
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You can click Add attribute name and value search to search for elements containing more 
than one attribute with a given name and/or value. To be matched, an element must match all of 
the specified entries. For example, you could search for all elements having an id attribute and 
a salary attribute. 


Maintaining the XML catalog 


Workbench provides a built-in catalog of widely used Schemas and DTDs. For example, the 
catalog includes the Schemas for XSL, WSDL, and XML Schemas; the Sun J2EE DTDs; and 
the SilverStream deployment plan DTDs. 


When you open an XML document that references a Schema or DTD, if the Schema or DTD is 
in the catalog, Workbench associates it with the XML document and enables context editing and 
validation. 


The Workbench catalog is based on the OASIS XML catalog standard. The OASIS XML 
catalog standard specifies a format for mapping external identifiers (public and system 
identifiers) and URI references to other URI references. This makes it possible to map, for 
example, a URI of a namespace to a local Schema file. The standard specifies that catalogs 
consist of one or more catalog entry files, each file specifying a set of catalog entries. 


LI For information on the OASIS standard, see http://www.oasis- 
open.org/committees/entity/spec.html. 


The built-in Workbench catalog consists of three directories in the Workbench Resources 
directory: 

e SchemaCatalog, which contains a set of Schemas 

e DTDCatalog, which contains a set of DTD files 


e CatalogFiles, which contains catalog entry files 


About the catalog entry files There are four built-in catalog entry files: 


e  dtdcatalog.xml, which lists all the preinstalled DTDs in the DTDCatalog directory 


e — schemacatalog.xml, which lists all the preinstalled Schemas in the SchemaCatalog 
directory 


e —user-dtdcatalog.xml and user-schemacatalog.xml, which are initially empty; you can use 
them to add entries to the catalog 
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The two DTD-related catalog entry files both point to DTD files in the DTDCatalog directory, 
that is, their base directory is specified as ../DTDCatalog. Similarly, the two Schema-related 
catalog entry files both point to Schemas in the SchemaCatalog directory, that is, their base 
directory is ./SchemaCatalog. 


An example For example, say you are working with the personal.xsd document that 
contains this declaration: 


<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 


Because the built-in Workbench catalog entry file schemacatalog.xml lists this URI and maps it 
to XMLSchema.xsd in the SchemaCatalog directory, when you open personal.xsd, Workbench 
locates its Schema in the local catalog without having to go out to the Internet for it. 


Adding to the catalog 


You might have Schemas and/or DTDs that you want to add to the Workbench catalog so they 
can be located when you open XML documents that use them. You can add Schemas and DTDs 
using the existing catalog structure or by extending the structure. 


Maintaining the existing structure The easiest way to add entries to the Workbench 
catalog is by using the existing catalog directory structure. 


> To add to the Workbench catalog using the existing structure: 


1. Add the .DTD or .XSD file to the DTDCatalog directory or SchemaCatalog directory. 


2. Open the corresponding user-editable catalog entry file in the Workbench 
Resources\CatalogFiles directory. 


e —user-dtdcatalog.xml, whose base directory is the Workbench DTDCatalog directory 
e —user-schemacatalog.xml, whose base directory is the Workbench SchemaCatalog 
directory 
3. Add the catalog entries to the file. 


You edit catalog entry files with the XML Catalog Editor, as described in “Using the XML 
Catalog Editor” on page 26. 


Extending the catalog structure You can also add entries to the XML catalog by 
extending the directory structure, that is, by creating additional directories of Schemas and 
DTDs and additional catalog entry files. 
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> To add to the catalog by extending the directory structure: 


1. Add the .DTD and/or .XSD files you want in the catalog to directories on your file system. 
You can organize the DTDs and Schemas any way you want, but you will need to create a 
catalog entry file for each directory containing DTDs or Schemas. 


2. Create catalog entry files for each of the directories using the XML Catalog Wizard: 


1. 
2. 


Select File>New. 

On the XML tab, select XML Catalog file and click OK. 
The XML Catalog Wizard displays. 

Specify the name of the catalog entry file. 


Specify its location. In order to have Workbench read the catalog entry file, place the 
file in the Workbench Resources\CatalogFiles directory. 


Specify the base URI, that is, the path to the directory containing the DTD or Schema 
files. It is through this base URI that Workbench is able to find the DTDs or Schemas 
listed in the catalog entry file. 


Click Finish. 
The catalog entry file is opened in the XML Catalog Editor. 
Add entries as described in “Using the XML Catalog Editor” on page 26. 


Using the XML Catalog Editor 
When you open a catalog entry file, Workbench displays it in the XML Catalog Editor. 
The XML Catalog Editor has three views: 


e A Tree View and Source View, which are the same as the corresponding views in the core 
XML Editor 


e A Catalog View, which presents an interface to the catalog entries 
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C:xwb21 eXtend/VorkbenchiResources \CatalogFilesischemacatalog xml (using: file: /C:. 
Schema URI 


Schema URI {URI 

http: dw ww ebxmlorg/namespacessradeP ... |Cpp-cpa-v1 _O.xsd 
http: dwrw w ebxml.org/BusinessProcess ebBPSS.xsd 
urn:uddi-org: api_v2 luddi_v2.xsd 

http: schemas .xmlsoap.org/wsdl! lwesdl. xsd 

http: Awww w3.org/2002/01 /xforms Ixforms.xsd 

http: JAW w3.org/1 999/chtml | chtmlichtmit A.xsd 
http: Awww w3 org" 999/xlink [xlink-1.0.xsd 

http: daww w3.org/2001 XMLSchema |XMLSchema.xsd 
urnoasis:names:te: entity: xmins:xm:catalog |xmicatalogs xsd 
http: Awww w3 org" 999/XSL/Transtorm [xsi xsd 








Insert’ Delete Browse 


Catalog View |= XML Source View: 





The Catalog View has one or more tabs: 
e A catalog entry file whose base directory is Resources/DTDCatalog has two tabs: Public 
Identifier and System Identifier 


e A catalog entry file whose base directory is Resources/SchemaCatalog has one tab: 
Schema URI 


e A catalog entry file whose base directory is any other directory has three tabs: Schema 
URI, Public Identifier, and System Identifier 


> To add a catalog entry: 


e Depending on whether the entry is for a Schema or DTD, select the appropriate tab and 
click Insert. 
e For a Schema, specify the Schema URI and the resolved URI 
e Fora DTD, specify either the public or system identifier and the resolved URI 


You can also edit and remove entries from the catalog entry file. 





CAUTION Don't delete preexisting DTDs or Schemas from the catalog, because Workbench 
might require them. 
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> To edit an entry: 


e Double-click the entry and make whatever edits you want. If you double-click a resolved 
URI value, the Browse button is enabled, allowing you to pick another file. 


> To delete an entry: 


e Select the entry and click Delete. 
The entry is removed from the catalog entry file (the Schema or DTD itself is unaffected). 


Using the XSL Editor 


Workbench provides an XSL Editor for you to create and maintain XSL style sheets. 


LL) For complete information about XSL, see http://www.w3.org/Style/XSL. 


> To create an XSL file: 


1. Select File>New. 
2. On the XML tab, select XSL file and click OK. 
Workbench generates a skeleton XSL document and displays it in the XSL Editor. 


Using the XSL Editor The XSL Editor provides an environment for editing, validating, 











and testing XSL files. 
Task Description 
Editing Use the XSL tab. You can use the keyboard shortcuts 
listed under “In Source View” on page 33. 
Validating the style sheet Select XSL Editor> Validate. 


Workbench displays the results in the Validate tab in 
the Output Pane. 


G For more information, see “Validating an XML 
document” on page 21. 
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Task 


Description 





Attaching or detaching 
Schemas/DTDs 


Select XSL Editor>Attach Schema or DTD or XSL 
Editor>Detach Schema or DTD. 


LL) For more information, see “Associating Schemas 
and DTDs with XML documents” on page 7. 





Testing transformations 








The Result tab allows you to see the result of the 
transformation specified by the XSL file: 


1. Select XSL Editor>Transform or press 
Ctrl+Shift+T and specify a file you want to apply 
the XSL style sheet to. 


2. Click the Result tab to see the result. 


Workbench displays the result of the transformation 
in the Edit Pane. If the transformation failed, errors 
are listed in the Messages tab in the Output Pane. 


. View the result of the transformation rendered in the 
default browser by selecting XSL Editor> View in 
browser. (You can also select this menu item from 
the XSL tab to specify an XML file to transform and 
render in a browser.) 


W 


(J For information about the default browser, see 
“General preferences” on page 14. 
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Keyboard shortcuts 


Here are the keyboard shortcuts provided in the XML Editor, XML Catalog Editor, and XSL 
Editor. 


In Tree View 


Navigation and display 


















































Keys Description 

Ctrl+A Expands all 

Ctrl+Shiftt+A Collapses all 

Ctrl+E Expands element group 

Ctrl+Shift+E Collapses element group 

Up Arrow Navigates to previous visible node 

Down Arrow Navigates to next visible node 

Left Arrow Collapses element group 

Right Arrow Expands element group 

Alt+Up Arrow Navigates to previous sibling (element within an element 
group) 

Alt+Down Arrow Navigates to next sibling 

Alt+Left Arrow Navigates to parent 

Alt+Right Arrow Navigates to first child 

Alt+Page Up Navigates to previous cousin (element with the same element 
path to the root) 

Alt+Page Down Navigates to next cousin 

Ctrl+Up Arrow Hides the selected element’s attributes 
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Keys Description 

Ctrl+Down Arrow Displays the selected element’s attributes 

Ctrl+Left Arrow Hides the selected element’s namespace declarations 

Ctrl+Right Arrow Displays the selected element’s namespace declarations 

Ctrl+Shift+tUp Arrow Hides the selected element’s attributes and namespace 
declarations 





Ctrl+Shift+Down Arrow Displays the selected element’s attributes and namespace 








declarations 
Ctrl+Q Toggles the display of attributes for all displayed elements 
Ctrl+Shift+Q Toggles the display of namespace declarations for all 


displayed elements 





Ctrl+Alt+Shift+Q Toggles the display of attributes and namespace declarations 
for all displayed elements 





Ctrl+Shift+G Displays the Schema Guide for the selected element 














Searching for text 


























Keys Description 

Ctrl+F Shows Find dialog 

F3 Navigates to next search result 

Shift+F8 Finds matching elements (displays Search Result icon, %) 
Alt+Shift+H Toggles display of Search Result icon 

Ctrl+Alt+Shift+H Clears the search 

F9 Finds next matching element 

Shift+F9 Finds previous matching element 
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Editing text 






























































Keys Description 

Ctrl+X (Cut) Cuts the current selection to the clipboard 

Ctrl+C (Copy) Copies the current selection to the clipboard 

Ctrl+V (Paste) Pastes the contents of the clipboard at the insertion 
point 

Ctrl+Shift+V Pastes the contents of the clipboard as the last child of the 
selected element 

Del (Delete) Deletes the current selection 

F5 Refreshes and collapses the tree 

Ctrl+Z Reverses editor actions (except save) 

Ctrl+Y Reverses Undo actions 

Ctrl+L Inserts new element as last child 

Ctrl+T Inserts new text as last child 

Ctrl+D Inserts new CDATA as last child 

Ctrl+Shift+L Inserts new element before selected node 

Ctrl+Shift+T Inserts new text before selected node 

Ctrl+Shift+D Inserts new CDATA before selected node 

Ctrl+K Inserts new attribute 

Ctrl+Shift+K Deletes selected attribute 

Ctrl+M Inserts new namespace declaration 

Ctrl+Shift+M Deletes selected namespace declaration 
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In Source View 


Moving the insertion point 





Keys 


Description 





Left Arrow, Right Arrow 


Moves the insertion point one character to the left or right 





Ctrl+Right Arrow 


Moves the insertion point one word to the right 





Ctrl+Left Arrow 


Moves the insertion point one word to the left 











Home Moves the insertion point to the beginning of the line 
End Moves the insertion point to the end of the line 
Up Arrow Moves the insertion point one line up 





Down Arrow 


Moves the insertion point one line down 


























Alt+Shift+T Moves the insertion point to the top of the window 
Alt+Shift+M Moves the insertion point to the middle of the window 
Alt+Shift+B Moves the insertion point to the bottom of the window 
Ctrlt+Home Moves the insertion point to the beginning of the document 
Ctrl+End Moves the insertion point to the end of the document 
PgUp Moves the insertion point one page up 

PgDn Moves the insertion point one page down 

Alt+Shift+F8 Moves the insertion point to matching begin/end tag 





Alt+Up Arrow 


Moves the insertion point to previous sibling (element 
within an element group) 





Alt+Down Arrow 


Moves the insertion point to next sibling 





Alt+Right Arrow 








Moves the insertion point to first child 
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Keys Description 

Alt+Left Arrow Moves the insertion point to parent 
Ctrl+G Displays Go to Line dialog 

Ctrl+L Toggles display of line numbers 











Selecting text 
































Keys Description 

Ctrlt+A Selects all text in the document 

Shift+Right Arrow Selects the character to the right of the insertion point 

Shift+Left Arrow Selects the character to the left of the insertion point 

Alt+J Selects the word the insertion point is on, or deselects any 
selected text 

Ctrl+Shift+Right Arrow Selects the word to the right 

Ctrl+Shift+Left Arrow Selects the word to the left 

Shift+Home Selects text to the beginning of the line 

Shift+End Selects text to the end of the line 

Shift+Up Arrow Selects text to the previous line 





Shift+Down Arrow 


Selects text to the next line 














Ctrl+Shift+Home Selects text to the beginning of the document 
Ctrl+Shift+End Selects text to the end of the document 
Shift+PgUp Selects text one page up 

Shift+PgDn Selects text one page down 
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Scrolling text 


























Keys Description 

Alt+U T Scrolls line containing insertion point to top of window 
TIP Press and release Alt+U, then press T 

Alt+U M Scrolls line containing insertion point to middle of window 
TIP Press and release Alt+U, then press M 

Alt+U B Scrolls line containing insertion point to bottom of window 
TIP Press and release Alt+U, then press B 

Ctrl+Up Arrow Scrolls the window up without moving the insertion point 

Ctrl+Down Arrow Scrolls the window down without moving the insertion point 





Modifying text 























Keys Description 

INSERT Switches between insert text and overwrite text modes 

Alt+U U Makes the selected characters or the character to the right 
of the insertion point uppercase 
TIP Press and release Alt+U, then press U 

Alt+U L Makes the selected characters or the character to the right 
of the insertion point lowercase 
TIP Press and release Alt+U, then press L 

Alt+U R Reverses the case of the selected characters or the character 
to the right of the insertion point 
TIP Press and release Alt+U, then press R 

F11 Reformats the tag the insertion point is on 
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Keys Description 

Shift+F11 Reformats the entire document 

Ctrl+Alt+O Opens the tag (for example, converts <a/> to <a></a>) 
Ctrl+Alt+C Closes the tag (for example, converts <a></a> to <a/>) 











Cutting, copying, pasting, and deleting text 









































Keys Description 
Ctrl+Z (Undo) Reverses (one at a time) a series of editor actions, except 
Save 
Ctrl+Y (Redo) Reverses (one at a time) a series of Undo commands 
Ctrl+X (Cut) Cuts the current selection and places it on the clipboard 
Ctrl+C (Copy) Copies the current selection to the clipboard 
Ctrl+V (Paste) Pastes the contents of the clipboard at the insertion point 
Delete (Delete) Deletes the current selection 
Ctrl+E Deletes the current line 
Ctrl+H Deletes the character preceding the insertion point 
Ctrl+Shift+Backspace Deletes text in the following sequence: 
1. Text preceding insertion point on same line 
2. Indentation on same line 
3. Line break 
4. Text on previous line 
Ctrl+W Deletes the current word or the word preceding the insertion 


point 
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Searching for text 





























Keys Description 

Ctrl+F3 Searches for the word the insertion point is in and highlights all 
occurrences of that word 

F3 Moves the insertion point to the next occurrence of the found 
word 

Shift+F3 Moves the insertion point to the previous occurrence of the 
found word 

Alt+Shift+H Toggles highlighting of words 

Ctrl+F Displays Find dialog 

Ctrl+R Displays Replace dialog 








Changing indentation 



































Keys Description 

Tab Shifts all text to right of insertion point to the right 

Ctrl+T Shifts text in line containing the insertion point to the right 

Ctrl+D Shifts text in line containing the insertion point to the left 
Bookmarks 

Keys Description 

Ctrl+F2 Sets or unsets a bookmark at current line 

F2 Goes to next bookmark 
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Specifying transformation (XSL Editor) 





Keys Description 














Ctrl+Shift+T Displays dialog for specifying file to transform 





In Catalog View, XML Catalog Editor 


Modifying text 











Keys Description 

Ctrl+B Displays dialog for changing the base URI, that is, the path to 
the directory containing the DTD or Schema files for the catalog 
entry file 
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8 WSDL Editor 





The WSDL Editor provides a quick and easy way to create, edit, and view WSDL documents. 
This chapter contains the following topics: 

e About WSDL 

e About the WSDL Editor 

e Creating anew WSDL document 

e Adding elements to a WSDL document 

e Validating a WSDL document 

e Displaying a stylized view 

e Publishing to a registry 

e Generating Web Service files from WSDL 


About WSDL 


WSDL (Web Services Description Language) is a general-purpose XML vocabulary for 
describing Web Services. Using WSDL, it is possible to describe (concisely and in a 
standardized manner) the interface, protocol bindings, and deployment details of Web-based 
services, at a level of detail sufficient for businesses to begin to interact online. 


LL) The complete WSDL standard can be found at http://www.w3.org/TR/wsdl. 


About the WSDL Editor 
The WSDL Editor lets you: 
e Create and edit WSDL documents (files with the .WSDL extension) 


e Easily create any of the four canonical WSDL document elements (message, port type, 
binding, or service) 


e Validate WSDL documents 
e View WSDL documents in stylized view and color-coded text view 


e Publish WSDL documents to Web Service registries 


The WSDL Editor also supports the editing features described in Chapter 6, “Source Editors”. 
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Creating a new WSDL document 


> To create anew WSDL document: 


1. Select File> New. 
2. On the Web Services tab, select WSDL and click OK. 


The WSDL Wizard displays. 


Specify WSDL Options 


Definition Name 





Target Namespace 
urn: some-urn 





Documentation 


IV Include WSDL template 





3. (Optional) Enter a Definition Name. 

4. (Optional) Enter a Target Namespace. This can be the Uniform Resource Name 
associated with this WSDL document. You cannot specify a relative URN. 

5. (Optional) In the Documentation text box, enter any human-readable comment or 
descriptive language you would like to associate with the definition element. 

6. Select the Include WSDL template check box if you want a skeleton document to be 


created for you using values provided in this wizard. Leave the check box unselected to 
start with a blank document. 
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7. Click Finish. 
A new WSDL document opens in the WSDL Editor. 


StockQuote.wsdl 





<?xml version="1.0"2> 
<definitions name="StockQuote™ 
targetNamespace="urn: some-urn"™ 
xmlns: tns="urn: some-urn™ 
xnlns="http: //schemas.xmlsoap.org/wsdl/" 
xmlns:xsd="http: //win.w3. org/1999/XMLSchema"™ 
xnlns: soap="http: //schemas.xnlsoap.org/wsdl/soap/"> 


</definitions> 














Adding elements to a WSDL document 


WSDL documents can contain four standard element types: message, port type, binding, and 
service. These element types build on one another with cascading references; so when you 
create a WSDL file, you should create the message section first, followed by the port type 
section, then the binding section, and finally the service section. 


The WSDL Editor offers dialog-based assistance in creating each of the four types. 


Adding a message element 


In WSDL, a message is an abstract definition of the data being exchanged. 


> To add a message element to a WSDL document: 
1. Position the insertion point where you want to insert the definition and right-click. 


A popup menu displays. 
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2. Select Insert WSDL Element>Message. 


Enter the information for the message element. 
Name: 





GetLastTradePriceOutput 


Documentation: 





Parts: 


Name | Typing 


body Element 












GK) Cancel) Help 


3. Specify the following information in the Message dialog: 











Option What to do 

Name Specify the value of the name attribute of the <message> 
element. 

Documentation (Optional) Specify any human-readable comment or descriptive 


language you would like to associate with this message. 





Parts Specify this information for each <part> element of your 
message: 


e The name attribute 
e The typing value (Element or Type) 
e Under Value, the element attribute 


To add another part entry to the message, click Add. To remove 
an entry, select the entry and click Delete. 











4. Click OK. 
A new message section is added to your document. 


<message name="GetLastTrade PriceOutput” > 


<part name="body" element="xsd1:TradePriceResult"/> 
</message> 
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Adding a port type element 


A WSDL port type is an abstract definition of the operations supported by a service and the 
communications mode (one-way, request-response, and so on) that will be used in the service. 


> To add a port type to a WSDL document: 


1. Position the insertion point where you want to insert the definition and right-click. 
A popup menu displays. 
2. Select Insert WSDL Element>Port Type. 





¥ Port Type Eg 
Enter the information for the port type element. 

Name: 

StockQuotePortType 


Documentation: 





Operations: 


Name Type Formats: Add | 
GetTradePrice Request-response bd Define... 
Delete | 














3. Specify the following information on the Port Type dialog: 




















Option What to do 

Name Specify the value of the name attribute of the <portType> 
element. 

Documentation (Optional) Specify any human-readable comment or descriptive 
language you would like to associate with this port type. 
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Option What to do 
Operations Specify this information for each <operation> element of your 
port type: 


e The name attribute 


e The type (One-way, Request-response, Solicit-response, or 
Notification) 


e Under Formats, click the Define button to specify the 
operation’s messages using the Define dialog 


The dialog has several control groups. Only those that are 
appropriate to the type of operation are enabled. For example, 
if you chose Notification as the type, only the Output control 
group is enabled. For each enabled group, you must specify a 
Name and Message appropriate to the operation for Input 
and Output. Specifying values for the Fault group is 
optional. 


To add another operation entry to the port type, click Add. 
To remove an entry, select the entry and click Delete. 














4. Click OK. 
A new port type section is added to your document. 


<portType name="StockQuotePortType"> 
<operation name="GetTradePrice"> 
<input name="input" message="tns:GetLastTradePriceInput"/> 
<output name="output" message="tns:GetLastTradePriceOutput"/> 
</operation> 
</portType> 


Adding a binding element 


A WSDL binding specifies concrete protocol and data format specifications for the operations 
and messages defined by a particular port type. 


> To add a binding to a WSDL document: 


1. Position the insertion point where you want to insert the definition and right-click. 


A popup menu displays. 
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2. Select Insert WSDL Element>Binding. 


Enter information for the binding element. 


Name: 





StockQuoteSoapBinding 


Documentation: 





Port Type: 


PtockQuotePortT ype X | 


Binding Protocol 
© SOAP Binding 
Style: 
pe 


Transport: 


Fite: Jischemas.xmlsoap.org/soap/nttp 


© HTTP Binding 


jet 


C User Defined 





3. Specify the following information on the Binding dialog: 





Option 


What to do 





Name 


Specify the value of the name attribute of the <binding> 
element. 





Documentation 


(Optional) Specify any human-readable comment or descriptive 
language you would like to associate with this binding element. 





Port Type 


Specify the port type for this binding. The dropdown list 
displays the names of the port types that you have created for 
this document (see “Adding a port type element” on page 5). 





SOAP Binding 


If your WSDL document will specify a SOAP binding, select 
SOAP Binding, then select a Style (RPC or Document) and 
specify a Transport value. 





HTTP Binding 








If an HTTP binding will be used, select HTTP Binding and 
enter the appropriate Verb (GET or POST). 
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Option What to do 
User Defined Select if you want to specify a custom binding protocol 
manually. 
4. Click OK. 


A new binding section is added to your document. 


<binding name="StockQuoteSoapBinding" type="tns:StockQuotePortType"> 
<soap:binding style="rpc" 
transport="http://schemas.xmlsoap.org/soap/http"/> 
<operation name="GetLastTradePrice"> 
<soap:operation 
soapAction="http://example.com/GetLastTradePrice"/> 
<input> 
<soap:body use="literal" 
namespace="http://example.com/stockquote.xsd 
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> 
</input> 
<output> 
<soap:body use="literal" 
namespace="http://example.com/stockquote.xsd" 
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> 
</output> 
</operation> 
</binding> 


Adding a service element 
A WSDL service names the entry-point address (or addresses) for the Web Service in question. 


These addresses are in the form of URIs and constitute ports. 


> To add a service to a WSDL document: 


1. Position the insertion point where you want to insert the definition and right-click. 


A popup menu displays. 
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2. Select Insert WSDL Element>Service. 





Enter information for the service element. 
Name: 
StockQuoteService 


Documentation: 





Parts: 


Name | Binding | Address Type 


‘StockQuotePort |StockQuoteSoapBi... SOAP 






Location 


http: example .com| 








3. Specify the following information on the Service dialog: 











Option What to do 

Name Specify the value of the name attribute of the <service> 
element 

Documentation (Optional) Specify any human-readable comment or descriptive 


language you would like to associate with this service. 





Ports Specify this information for each <port> element of your 
service: 


e The name attribute 


e The binding value; the dropdown list displays the names of 
the bindings you have created for this document (see 
“Adding a binding element” on page 6) 


e The address type (None, SOAP, or HTTP) 


e The location (the URI by which your service will be 
available) 


To add another port entry to the service, click Add. 
To remove an entry, select the entry and click Delete. 
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4. Click OK. 
A new service entry is added to your document. 


<service name="StockQuoteService"> 
<port name="StockQuotePort" binding="tns:StockQuoteBinding"> 
<soap:address location="http://example.com/stockquote"/> 
</port> 
</service> 


Validating a WSDL document 


When a WSDL document is displayed in the Edit Pane, you can validate the document by 
clicking the Validate button (which looks like a check mark) in the toolbar. If the document is 
validated, you see this dialog: 


Document is well-formed. 





Otherwise, you see a dialog giving information identifying the malformed statement(s) in the 
document. 





CAUTION You should carefully review your WSDL even if the document validation is 
successful. The W3C WSDL specification allows for extensibility elements 
throughout all levels of a WSDL document. So if you build the document without 
using the dialogs or do a lot of cut-and-paste from other sources, it is possible that 
the document will test as valid but not be what you want. 
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Displaying a stylized view 


By default, WSDL documents are displayed in a color-coded text-edit view—the normal view 
for working on WSDL documents. You can also display a stylized view of WSDL documents, 
created by applying an XSL style sheet to your document. The WSDL Editor comes with two 
built-in style sheets: Summary and Detail. 


> To display a stylized view of a WSDL document: 


1. Open the WSDL document. 
2. Click the Stylized tab at the bottom of the WSDL Edit Pane. 


The view changes to stylized. 


CWINNT Profiles bhildebrand'Desktop Quotation wsdl 


StockQuote WSDL Definit Z 
targetNamespace: http://example.com/stockquote.wsdl 


service: Stock QuoteService 
port: name: Stock QuotePort 
binding: tns: Stock QuoteBinding 
soap:address: location: http: //example.com/stockquote 
binding: Stock Quote SoapBinding 
type: tns: Stock QuotePortType 
soap:binding: style: document 
transport: http://schemas.xmlsoap.org/soap/htip 
operation: GetLastTradePrice 
soap:operation: soapAction= http://example.com/GetLastTradePrice 
style= 
portType: Stock QuotePortType 
operation: name: GetLastTradePrice 


input: name: 


O XML) FT Stylized 


In this example, the Summary style sheet has been applied to the document. 











> To choose a different style for the stylized view: 


1. With the Stylized tab selected, right-click in the WSDL Edit Pane. 
A popup menu displays. 
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2. Select an item from the Stylesheets submenu: 


e Details provides a detail-oriented plain-text view of the WSDL document (with no 
XML tags) 


e Summary provides a more concise view of WSDL contents 


e Custom opens a dialog that allows you to choose your own XSL style sheet for 
rendering a custom view, and/or setting a default style sheet 


Ei Select Style Sheet | x! 
oe System [Summary z] 


C custom | Brayse | 








[ Set as default 


Choose one of the following: 








Option What to do 





System Select to use one of the built-in style sheets (Summary or 
Details) as the basis for the stylized view 





Custom Select to use the style sheet of your choice, then enter the path to 
the style sheet (or use the Browse button to open a standard file 
navigation dialog) 














TIP You can optionally select the Set as default check box to apply the style sheet 
you’ve chosen as the default in stylized views. Your preference will persist 
across Workbench sessions. 


Publishing to a registry 


When you have created a WSDL document, you can publish it to a registry. 


LO For more information, see “Publishing to a registry” on page 293. 





12 Publishing to a registry 


eXtend Workbench Tools Guide 





Generating Web Service files from WSDL 


A WSDL document describes a Web Service. You can invoke the Web Service Wizard from the 
WSDL Editor to generate the Java classes needed to implement or consume that Web Service. 


> To generate Java classes: 


1. Make sure a Workbench project is open. 
2. Open the WSDL document in text view. 
3. Click the Generate Java Class button. 


The Web Service Wizard is invoked. 


(J For more information, see Chapter 5, “Web Service Wizard”. 
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This chapter describes the registry browsing and publishing functionality provided in 
SilverStream eXtend Workbench. It contains the following topics: 


About UDDI 

About the Registry Manager 
Defining registry profiles 
Browsing registries 

Retrieving WSDL from the registry 
Publishing to a registry 


About UDDI 


The business registry standard covering Web Services is UDDI (Universal Description, 
Discovery, and Integration). UDDI is designed to give businesses a uniform way to describe 
their services, discover other companies’ services, and understand the methods needed to 
conduct e-business in an automated or semiautomated way with remote partners. UDDI forms 
the basis for the registry management functionality. 


(AA) 


To learn more about UDDI, see the complete standard at http://www.uddi.org. 


About the Registry Manager 


Workbench provides a Registry Manager, accessible through the Registries tab in the 
Navigation Pane, and a facility for defining registry profiles. 


Workbench registry capabilities include: 


Defining registry profiles 

Selecting registries to include in the search process 

Viewing business information on selected businesses in a given registry 
Viewing information on Web Services offered by a given business 


Searching for businesses or services within a registry or group of registries, optionally 
using extended query parameters 


Publishing new services to a registry 
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Defining registry profiles 


Registries are specified by URL and can be local or Web-based. Before accessing a registry in 


Workbench, you define a profile for that registry. Workbench comes with some predefined 
registry profiles. 


> To define a registry profile: 


1. 


Select Edit>Profiles from the menu. 
The Profiles dialog opens. 
Select the Registries tab. 


ZZ Profiles Eg 


B Servers | eu Databases 


Registry Profiles are used for deploying Web Services. They specify the 
information necessary to deploy and inquire a given registry. 








Profile name: fen Public Registry z] New... | 


| Registry type: UDI eden 
| Registry version: 1.0 








| Registry specific information: 
| Inquiry URL http: daww -3 ibm.comiservices/uddiinguiryapi 


| Publish URL https: /Avwew-3.ibm.com/services/uddi/protect/publishapi 
| User name 


| [F Include in Registry Search 











OK Cancel Help 
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3. Ifyou are editing or deleting an existing profile, select it from the Profile name list box 
and click Edit or Delete. If you are creating a new profile, click New. 


3% Create a New Registry Profile x| 
Profile name: | 


Registry type: UDDI + ] 


Registry version: 1.0 





| Registry specific information: 
| 


| Inquiry URL | 
| Publish URL | 
| Username | 


Credential | 


| 
| JV) Include in Registry Search 











4. Specify the following information: 

















Option Description 

Profile name Name of the profile 

Registry type Type of registry (default is UDDI) 

Inquiry URL The URL through which the registry can be queried 
Publish URL The URL through which new services can be published 


to the registry 





User name and Credential The information (if any) that the registry provider 
assigned to you for publishing access 





Include in Registry Search Specifies whether you want to include this registry in 
the default search set 














5. Click OK. 


Once you have defined a registry profile, you can use the Registry Manager to browse the 
registry and you can publish services to the registry. 
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Browsing registries 


The Registry Manager allows you to browse registries through the Registries tab in the 
Navigation Pane. There are two subpanes within the Registries tab: the Business Pane and the 
Service Pane. 


Business: © 











Methods oO O āå g 
) Microsoft Test Registry 
g- a XMethods 
eb services resource site 
EC) Services 
i Metho et < je es 
XMethods Delayed Stock Quotes 
XMethods Pacific Bell SMS Service 
Methods Barnes and Noble Quote xl 





4 


[ET E ee a 
B Directory | E Project | [= Open) ČR) Registries 





> 


Information displayed 


The Registry Manager displays the following types of information. 


Business Pane The business section of a registry might include these types of information: 

















Information Icon | Description 

Business name m Business name used in this registry 
Description Short phrase describing the business 
Categories Categories to which the business belongs 























Classification schemes come from at least three sources: 
NAICS codes for industry segments, UNSPSC for product 
and service classifications, and geographic information 
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Information Icon | Description 
Identifiers Information about the business, such as a DUNS number 
Services © A list of services offered by the business, such as Web 











Services callable via HTTP and other services such as sales 
and technical support contact information 


You can select a service name to display its details in the 
Service Pane 





Service Pane A service entry in a registry might include these types of information: 





Information 


Icon 


Description 





Service name 


© 


The name of the service 





Business name 


The business offering the service 


















































Description A short phrase describing the service 

Binding The URL for invoking the service 

tModel tM Data describing the service 
A UDDI registry stores the data as a tModel, which is a set of 
name/value pairs; the tModel node may be followed by a 
description 

Overview URL The URL of a document describing how to use the tModel 
data 
For a Web Service, this is usually a WSDL document 

Categories Categories for the service 


The categorization has two parts: a name (for example, uddi- 
org:types) and a value (for example, wsdlSpec). The value 
wsdlSpec specifies that a WSDL document is available for the 
service. Other types of services can use other classification 
schemes. 
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Popup menus 


Each pane in the Registry Manager has a popup menu. 


Business Pane To view the popup menu for Business, place the cursor in an entry in the 
Business Pane and right-click. The following menu displays. 





Menu item Description 





Copy Text Allows you to copy text from the currently selected business tree node 
to another area or file 





Clear Tree Clears the pane of business information that you retrieved from your 
search 





Advanced Search | Allows you to perform a sophisticated search by business 











LU) For more information, see “Searching by business” on page 7 





Service Pane To view the popup menu for Service, place the cursor in an entry in the 
Service pane and right-click. The following menu displays. 





Menu item Description 





Copy Text Allows you to copy text from the currently selected service tree node 
to another area or file 





Clear Tree Clears the pane of service information that you retrieved from your 
search 





Retrieve WSDL Retrieves the WSDL for the selected service from the registry. You 
can also do this using the Retrieve WSDL button. 





Delete Service Deletes the selected service (if you have permission). Asks you to 
confirm before deleting the service. 





Advanced Search | Allows you to perform a sophisticated search by service 


LU) For more information, see “Searching by service” on page 10 
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Action buttons 


The following illustration shows the location of the various action buttons on the Business and 
Service panes. 


Keyword box Advanced Search Stop 













Business: 
Methods 
E (R) Microsoft Test Registry 
i gaj XMethods 






Search 


eb services resource site 
i ` : 
BC) Services 


XMethods Currel 





XMethods Delayed Stock Quotes 
Methods Pacific Bell SMS Sdrvice 
Methods Barnes and Noble Quote 


Retrieve WSDL 


Delete Service 





i R 

Serice: UX fh Oo 
fkttethods Currency Exchange Rates ce 
LR) Microsoft Test Registry 








Methods 





a-@ 
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HCE 
B Directory | a Project | [3 Open R) Registries 


Searching by business 


You search by business in the Business Pane. 


> To search businesses by name or keyword: 


1. Enter a complete or partial business name or keyword in the text box below Business. 


TIP You can also enter a group of business names separated by a vertical bar, which 


allows you to search for multiple groups of businesses. For example: 
XMethods|IBM|Sun. 


2. Click the Search button (shaped like a downturned arrow). 


While the search is underway, the Stop button (normally grayed out) is red. The search can 


take several minutes. To interrupt the search, click the Stop button; partial search results 
will display in the Business Pane. 
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> To set advanced business search criteria: 
1. 
2. 


A list of matching businesses appears in tree-view form. Each top-level node in the tree is 
a registry, each child of a registry is a business name, and below each business is detail 
information consisting of descriptions, categories, and services. 





Business: Hh © 
fiMethods 00 an 
=}€R) Microsoft Test Registry 

(=) Sf XMethods 


Web services resource site 
EC) Services 





XMethods Delayed Stock Quotes 
XMethods Pacific Bell SMS Service 
+ Methods Barnes and Noble Quote l 








Clicking a service entry in the (upper) Business tree causes that service’s detail 
information to appear in tree form in the (lower) Service Pane. 


Business: 

















R ) Microsoft Test Registry 
B- g XMethods 


+-Neb services resource site 
EC) Services 





XMethods Delayed Stock Quotes 
Methods Pacific Bell SMS Service 
Methods Barnes and Noble Quote xl 


Service: 


a Currency Exchange Rates cys 




















Fo Pe et | >l 


Leave the keyword text box blank. 
Click the Advanced Search button (shaped like binoculars). 
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The Business Discovery Criteria dialog displays. 


Business Discovery Criteria x| 


Select one of five Search criteria groups below. Enter Search parameters 
in the selected group, add Find qualifiers. Press OK button to begin the search. 
You may use the '%' symbol as a wildcard that matches any character. 


Discover via: 


Business Name 








rCriteria ne —_ 


Starting with: 


poi oaaao 


Profiles — Sort By ) pOptions 


IBM Public Registry [7 Name 7 Ignore case 
IBM Test Registry | e G 
Microsoft Tes’ r [7 Exact Match 




















3. Select one of the search-criteria options: 


e Business Name—Enter a complete or partial business name or list of names separated 
by a vertical bar (|) in the Starting with text box. 


e Identifier—Select one of the following: D-U-N-S or Thomas Register (catalog 
names) from the dropdown list. Enter a key from the catalog (partial or complete) in 
the Starting with text box; this entry can contain numeric values and dashes. 

e Locator—Select one of the following from the dropdown list: NAICS (North 

American Industry Classification System), UNSPSC (United Nations Standard 
Products and Services Classification), or GEO (geographical). 
Enter a key from the catalog (partial or complete) in the Starting with text box if you 
selected NAICS or UNSPSC; this entry can contain numeric values. Enter a country 
(region) abbreviation for GEO. If you selected NAICS or UNSPSC, you can click the 
ellipses and pick an item from a list of choices. 


e Service Type Name—Select to search businesses associated with a particular tModel. 


e Discovery URL—Enter an IP address or portion of an IP address for the URL in the 
Starting with text box. 
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4. 


Select search and sort options: 

e InSort By, specify whether to sort by name or date, in ascending or descending order. 
The most common technique is to sort by name (alphabetically) in ascending order or 
by date (numerically) in descending order. Sorting by date works within groups of 
businesses with identical names. 


e In Options, select Ignore Case and/or Exact Match. 


Under Profiles, select the registry or registries to search from the dropdown list. Those 
you specified in the Profiles dialog for automatic searching are already selected. To 
override the search list, select one or all of the registries in the list. To return to the original 
(default) registries, click Reset. 


Click OK. 
The search begins. 


Searching by service 


You search by service in the Service Pane. 


> To search services by name or keyword: 


1. 


Enter a complete or partial service name or keyword in the text box below Service. 


TIP You can also enter a group of service names separated by a vertical bar, which allows 
you to search for multiple groups of services. 


Click the Search button (shaped like a downturned arrow). 


While the search is underway, the Stop button (normally grayed out) is red. The search can 
take several minutes. To interrupt the search, click the Stop button; partial search results 
display in the Service Pane. 


A list of matching services appears in tree-view form. Each top-level node in the tree is the 
registry that was searched; each immediate child of a registry is a service name; and 
children of the service node(s) contain detail information consisting of the business name 
associated with the service, a description of the service, and bindings for the service. 


Clicking a service node in the (lower) Service tree causes that business’s detail 
information to appear in tree form in the (upper) Business Pane. 
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> To set advanced service search criteria: 
1. Leave the keyword text box blank. 
2. Click the Advanced Search button (shaped like binoculars). 
The Service Discovery Criteria dialog box displays. 


Select one of three Search criteria groups below. Enter Search parameters 
inthe selected group, add Find qualifiers. Press OK button to begin the search. 
You may use the '%' symbol as a wildcard that matches any character. 


Criteria Group: 


Service Name 





-Criteria 





Starting with: 


peto ooo 


Prolite ) Sort By Options— 
IBM Public Registry | | [ Name 
IBM Test Registry | & C 
Microsoft Test Registry 





[ Ignore case 


[7 Exact Match 





[L Date 

















3. Select one of the search-criteria options: 


e Service Name—Enter a complete or partial service name in the Starting with text 
box. 


e Locator—Select one of the following: NAICS (North American Industry 
Classification System), UNSPSC (United Nations Standard Products and Services 
Classification), UDDITYPE, or GEO (geographical) from the dropdown list. 


Enter a key from the catalog (partial or complete) in the Starting with text box if you 
selected NAICS, UNSPSC, or UDDITYPE; this entry can contain numeric values. 
Enter a country (region) abbreviation for GEO. If you selected NAICS, UNSPSC, or 
UDDITYPE, you can click the ellipses and pick an item from a list of choices. 


e Service Type Name—Allows the search of services associated with a particular 
tModel. 
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4. 


Select search and sort options: 


e InSort By, specify to sort by name or date, in ascending or descending order. The most 
common technique is to sort by name (alphabetically) in ascending order or by date 
(numerically) in descending order. Sorting by date works within groups of services 
with identical names. 

e In Options, select Ignore Case and/or Exact Match. 

Under Profiles, select the registry or registries to search from the dropdown list. Those 

you specified in the Profiles dialog for automatic searching are already selected. To 

override the search list, select one or all of the registries in the list. To return to the original 

(default) registries, click Reset. 


Click OK. 
The search begins. 


A tree of matching services is built in the Service Pane. Clicking a service node in the 
(lower) Service tree causes that business’s detail information to appear in tree form in the 
(upper) Business Pane. 


Retrieving WSDL from the registry 


After you have found the service you searched for, you can retrieve the WSDL definition for this 
service from the registry. For this you use the Service Pane. 


> To retrieve a WSDL definition from the registry: 


1. 
2. 


Highlight the service node. 
Click the Retrieve WSDL button in the Service Pane. 


R 
Gd 
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If a definition for the service exists 

















Business: 


fivtethoas È 





a 


E R ) Microsoft Test Registry 
gj XMethods 
Web services resource site 
8 ie) l Services 
iM 
XMethods Delayed Stock Quotes 
XMethods Pacific Bell SMS Service 
Methods Barnes and Noble Quote 


| a 











Service: 
E tR) Microsoft Test Registry 
a-@ 
ggj XMethods 


Returns exchange rates between 2 countries’ currenci 








i 


| 
4 
Directory Project | [— Open (R) Registries 


LJ 
Chapter 8, “WSDL Editor”. 


Publishing to a registry 


w | 


, the WSDL Editor displays the WSDL information. 


CurrencyExchangeRate. wsdl 





















<?xml version = "1.0"?> 
<definitions name "XMethods Currency Exchange" targetNamesp 
<message name "getRateRequest"> 


<part name = “countryl" type = "xsd:string" /> 

<part name = “country2" type = "xsd:string"/> 
</message> 
<message name = “getRateResponse"> 

<part name = "Result" type = "xsd:float"/> 
</message> 


<portType name “CurrencyExchangePortType"> 


<operation name = “getRate™> 
<input message = “tns:getRateRequest" /> 
<output message = “"tns:getRateResponse” /> 


</operation> 
</portType> 
<binding name “CurrencyExchangeBinding” type "tns: Cur 

<soap:binding style "rpc" transport = “http: //schem 


<operation name = “getRate"> 
<soap:operation soapAction="http: //xmethods.net/C 
<input> 


v 














For information about the WSDL Editor, including different ways to view the WSDL, see 


When you have created a WSDL document in the WSDL Editor, you can publish it to a registry. 


LQ 


> To publish to a registry: 


1. 
2. 


Be) 


For information about the WSDL Editor, see Chapter 8, “WSDL Editor”. 


Open the WSDL document in the WSDL Editor. 
Click the Publish to Registry button on the toolbar. 





Publishing to a registry 
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The WSDL Publishing Options dialog displays. 


WSDL Publishing Options x| 
Registry Profile: 
[Local Registry z] 
Business Name: 
Hone, Inc. D 
WSDL Publish URL: 


BervicestestService 








os 


Specify these options: 
e Registry Profile—Select the registry you want to publish to. 


e Business Name—Specify the business to associate the service with. Click the Lookup 
button to look up businesses in the registry. 


e WSDL Publish URL—Specify the URL to which the service will be published. 
Click OK. 
If your service was successfully published, you see a confirmation dialog. 


If the service was not published, you see a dialog describing the error. 
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1 0 Deployment Descriptor Editor 





The Deployment Descriptor Editor provides a quick and easy way to construct and populate 
J2EE-compatible deployment descriptors. This chapter describes the Deployment Descriptor 
Editor and includes these topics: 

e About deployment descriptors 

e About the Deployment Descriptor Editor 

e Using the Deployment Descriptor Editor 


About deployment descriptors 


A deployment descriptor is an XML document that provides information about the 
components of a J2EE module (such as a WAR or an EJB JAR) or application (such as an EAR). 
The deployment descriptor provides data that is required for both of the following: 


e Application assembly—to describe how a component is or should be used 
e Deployment—to define deployment needs such as roles and resource references 


Sun has defined the contents and structure for a deployment descriptor for each J2EE 
component. For more information, see JZEE Deployment Descriptor DTDs in the online 
Reference. 


How deployment descriptors are created Workbench automatically constructs and 
adds a J2EE-compatible deployment descriptor file to your project in the appropriate location, 





as follows: 
J2EE Deployment 
component descriptor file Directory location 





Application client | application-client.xml | /META-INF 














EAR application.xml 

EJB JAR ejb-jar.xml 

RAR ra.xml 

WAR web.xml /WEB-INF 
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As you add J2EE components to a project, Workbench adds the corresponding elements to the 
deployment descriptor when it has enough information to do so. 


About the Deployment Descriptor Editor 


The Deployment Descriptor Editor allows you to fine-tune the deployment descriptor by 
modifying or completing entries that Workbench is unable to complete automatically. 


The Deployment Descriptor Editor displays the deployment descriptor elements as expandable 
nodes. The nodes correspond to elements of the deployment descriptor DTD. All possible 
deployment descriptor entries are represented graphically, so you can use the interface to help 
you add the appropriate entries without having to memorize the DTD. 


Here is a sample Deployment Descriptor Editor for an EJB project: 





¥ SilverStream (SilverBooksE ar) - Ear Deployment Descriptor Editor 
File Edit View Search Project Documents Help 
































LeM@al*+OBbBa|BS Sl eMe SilverStream 
Vew ung SS E E AE TENE OEE sr > 
oá am Deployment Descriptor: [Enterprise Archive = 
jol uaia = & Enterprise archive: SitverBooks 
P Gy. = é| Modules 
g ShoppingCartEJB.spt 
HÉ SiverBookswar.spt GBS AccesaDate jer 
GE sre Ap ShoppingCart jar 
silverbooks.war 
ist Roles 
{E} Directory l 
L Open Descriptor I fed xm] 




















4 
‘Se Baie] Gr Vetieste] gs vepioy Ee Find J 


J RW 











TIP You can view or edit the deployment descriptor in raw XML by choosing the XML tab. 
The Deployment Descriptor Editor opens in the mode (raw XML or tree view) in use 
when it was last saved. 


Nodes displayed in bold (like Environment and Persistent Fields) allow child nodes to be added 
or removed. You can add or remove these nodes by right-clicking and selecting from the popup 
menu. 
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Many of the nodes require additional information, and you can provide this information by 
completing a property sheet. To display the Property Inspector for a node, highlight the node, 
right-click, and select Properties. 


To save the changes to the deployment descriptor file in the archive, select File>Save (or click 
the Save icon). 


Using the Deployment Descriptor Editor 


You can use the Deployment Descriptor Editor either to fine-tune the default deployment 
descriptor created by Workbench or to create a new deployment descriptor. 


> To create a deployment descriptor: 

Open the project for which you want to create the new deployment descriptor. 
Select File>New. 

Select the J2EE tab. 

Select Deployment Descriptor and click OK. 


2. JO: dN 


Workbench constructs the deployment descriptor shell based on the contents of the project 
and displays the shell in the Edit Pane. 


> To associate a deployment descriptor with a project: 


NOTE Ifyou created a deployment descriptor outside the Workbench environment, you can 
still use it with a Workbench project by following these steps. 

1. Open the Workbench project that you want to associate the deployment descriptor with. 

2. Choose the Directory Pane. 

3. Double-click the deployment descriptor you want. 


You are prompted to associate the descriptor with the current project, a different project 
(which you can choose), or to edit the deployment descriptor in XML mode. 


4. Choose the option to associate the descriptor with the current project, then choose OK. 
Workbench opens the deployment descriptor in the Deployment Plan Editor. 


5. Save the deployment descriptor to complete the association. 
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> To modify a deployment descriptor: 


1. Open the project whose deployment descriptor you want to modify. 


2. Highlight the project file (the SPF), right-click, and select Open Deployment Descriptor 
from the popup menu. 


You are prompted for your Build preferences. 


Once you specify the Build preferences, the Deployment Descriptor Editor opens the file 
ready for editing. 


> To add a deployment descriptor element: 
1. Open the deployment descriptor for editing. 
2. Highlight the descriptor element, right-click, and choose Add from the popup menu. 
The editor adds a new element with the title UntitledX XX. 


3. Highlight the new element, right-click, and choose Properties from the popup menu to 
launch the Property Inspector so you can define any necessary values. 


> To remove a deployment descriptor element: 


1. Open the deployment descriptor for editing. 
2. Make sure the Descriptor tab (not XML tab) is selected. 


3. Highlight the descriptor element you want to remove, right-click, and select Delete from 
the popup menu. 


NOTE If Delete is not available as a menu option, the element is not removable. 


Validating a deployment descriptor 


The Deployment Descriptor Editor automatically checks your work as follows: 














When you The Deployment Descriptor Editor 

Switch mode (GUI to XML and vice versa) | Checks the syntax of the deployment 
descriptor 

Save the deployment descriptor Validates the current deployment descriptor 
against the DTD 











But you can force validation anytime. 
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> To force validation of a deployment descriptor: 


e Choose Validate Archive from the Project menu. 
This validates both the deployment descriptor and the archive. 
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1 1 Deployment Plan Editor 





The Deployment Plan Editor provides a quick and easy way to construct and populate 
deployment plans needed for deploying JZ2EE modules and applications to a SilverStream 
eXtend Application Server. This chapter describes how to use the Deployment Plan Editor and 
includes these topics: 

e About Deployment Plans 


e Using the Deployment Plan Editor 


About Deployment Plans 


A SilverStream deployment plan is an XML document that describes how a J2EE module 
(such as a WAR or an EJB JAR) or application (such as an EAR) should run in theSilverStream 
eXtend Application Server environment. 


A SilverStream deployment plan allows you to map declarative data from the deployment 
descriptor to the appropriate resource in the target server environment. For example, you can 
map resource references to actual data sources or map roles to actual users or groups. 


SilverStream has defined the contents and structure for a deployment plan for each J2EE 
component. For more information, see SilverStream Deployment Plan DTDs in the online 
Reference. 


NOTE Other application servers will require different types of information (possibly in 
different formats) for deployment. To deploy JZ2EE components on another J2EE 
application server, see the application server vendor’s documentation. 


Using the Deployment Plan Editor 
This section describes how to use the deployment plan editor to perform these tasks: 
e Create a deployment plan 
e Modify a plan 
e Associate a deployment plan with a project 


e Validate a deployment plan 
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> To create a deployment plan: 


1. 


a ae 


Make sure you have built the archive and added appropriate items to the deployment 
descriptor. 


Open the project for which you want to create the deployment plan. 
Choose File>New. 

Choose the J2EE tab. 

Choose SilverStream Deployment Plan and click OK. 


The Select Project For Deployment Plan dialog displays. 


Select project: 


[BiverBooksEar v | 





ShoppingCartEJB 


SilverBooksBeans 





Select destination server type: 


[Siiverstream 3.7.3 7] 





Choose a project from the Select project dropdown. 

NOTE When the project is an EAR, you see multiple files in the dropdown. 

Choose the destination server type from the server type dropdown and click OK. 

NOTE The server type listed when the dialog opens is the one specified as the default in 
Deployment preferences (Edit>Preferences). For more information, see 
“Deployment preferences” on page 18. 


The Deployment Plan Editor constructs a deployment plan based on the project type. The 
editor uses the project’s compiled code and the deployment descriptor to determine the 
deployment plan entries for a specified project. The deployment plan elements are 
displayed in a tree structure. 
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Whenever you change the deployment descriptor, Workbench updates the deployment 
plan to match the changes when you next edit the deployment plan. 


Here is a sample deployment plan for an EAR. It contains three EJB modules and a WAR: 











































W SilverStream (SilverBooksE ar) - Ear Deployment Plan Editor olx] 
File Edit View Search Project Documents Help 
caga nnsa) SilverStream 
| RRE on force leyou M C:Asilverbooks'SybaseASA\silverbooks plan xml 3 
-2 TEET] = & Enterprise Archive = 
a pd SilverBooksBeans.spt = Ap EJB Module ShoppingCart jar 
[E$ AccessDataEJB.spf @ ShoppingCart sssw/SilverBooks/appserver AJShoppingCart 
i) E = @ Order sssw/SilverBooks/appserver/SybaseASA/Order 
H É SilverBooksWar spt a W persistent Fields 
a sre W@W m_customerld CUSTOMERID 
W m_orderDate DATEORDERED 
@ m_orderld ORDERID 
W@W m_shippingCost A 
@ in_shipvia 
= Finder Methods 
avaLanginteger0 
= @ Orderitem ri/SybaseASA/Orderltem 
3 W Persistent Fields 
W@W m_bookid BOOKID 
@ m_discount DISCOUNT 
W m_orderid ORDERID 
W m_quantity QUANTITY 
W m_unitPrice UNITPRICE 
D = (PFinder methods 
T Directory | mm ORNERNET AIS ORDERINs iaval annintenert z 














Ls] 
a Build] E Validate Bs Deploy 








TIP You can view or edit the deployment plan in raw XML by choosing the XML tab. 
The Deployment Plan Editor opens in the mode (raw XML or tree view) in use when 
it was last saved. 


8. Choose File>Save (or click the Save icon). 


If there are other SilverStream deployment plans associated with this project, you will be 
asked whether you want to make the new deployment plan the current one. 


9. Click Yes to make it the current deployment plan. 


> To modify an existing deployment plan: 


1. Open the project whose deployment plan you want to modify. 


2. Highlight the project file (the SPF), right-click, and select Open Deployment Plan from 
the popup menu. 
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3. If your project has more than one deployment plan, choose the deployment plan from the 
dropdown and click OK. 


Workbench displays the deployment plan in the Edit Pane. 


4. Highlight a deployment plan element, then right-click and select Properties from the 
popup menu. 
Use the Property Inspector to modify values for different elements. In some cases, you can 
double-click an element to open a dialog that lets you enter data more quickly than 
through the Property Inspector. 


> To associate a deployment plan with a project: 


NOTE Ifyou created a deployment plan outside the Workbench environment, you can still use 
it with a Workbench project by following these steps. 

1. Open the Workbench project you want to associate the deployment plan with. 

2. Choose the Directory Pane. 

3. Double-click the deployment plan you want. 


You are prompted to associate the plan with the current project, a different project (which 
you can choose), or to edit the deployment plan in XML mode. 


4. Choose the option to associate the plan with the current project, then choose OK. 
Workbench opens the deployment plan in the Deployment Plan Editor. 
5. Save the deployment plan to complete the association. 


6. Choose Yes when prompted to mark the deployment plan as current. 


Validating a deployment plan 


The Deployment Plan Editor automatically checks your work as follows: 











When you The Deployment Plan Editor 

Switch mode (choose the Descriptor or the | Checks the syntax of the deployment plan 
XML tab) 

Save the deployment plan Validates the deployment plan against the 


DTD 














But you can force validation anytime. 
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> To force validation of a deployment plan: 


e Choose Validate Archive from the Project menu. 
This validates both the deployment plan and the archive. 
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1 2 Debugger 





The SilverStream Debugger lets you find runtime errors in your Java applications by controlling 
and monitoring the execution of Java code. You can debug server-side objects (such as J2EE 
applications) and client-side objects, either on a local host machine or remotely on distributed 
machines. 


NOTE By default, when you launch a debugger from within Workbench, the SilverStream 


Debugger is launched. If you want to use a different debugger, you can specify that 
debugger so it is launched from within Workbench. For more information, see 
“Specifying a debugger” on page 43. 


This chapter describes the following: 


Concepts you need to know 

About the Debugger 

Debugging server applications 
Debugging client applications 

Managing program execution 

Analyzing the behavior of the application 
Debugger keyboard shortcuts 


Concepts you need to know 


You should review the following concepts before you use the Debugger. 





Concept Description 





Breakpoint You can set a breakpoint on an executable line in your code where 
you want execution to stop temporarily. When you set a breakpoint 
in code, the program stops running before executing the line 

containing the breakpoint, then turns control over to the Debugger. 








Deadlock A deadlock is a condition that occurs when two processes are each 
waiting for the other to complete before proceeding. Both 
processes hang. 

















12 Debugger 








Concept Description 





Instance variable An instance variable is a field declared within a class declaration 
without using the keyword static. 





Local variable A local variable is declared inside a particular method. Only code 
that is contained in the method can access a local variable. 





Monitor In Java, a monitor is an exclusive lock on an object. Locks are 
used in thread synchronization.When a method is programmed to 
be synchronized, it cannot be run in multiple threads concurrently. 
When a synchronized method is entered, it acquires a monitor on 
the current object (the object whose method was called). The 
monitor prevents other synchronized methods in the object from 
executing. When the synchronized method returns, its monitor is 
released, allowing other synchronized methods in the same object 
to run. 





Thread A thread is a single execution stream in a program. Java is a 
multithreaded language, which means that you can have many 
execution streams operating at one time. In Java, threads are 
represented by the Thread object. 
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About the Debugger 


The SilverStream Debugger provides several capabilities for diagnosing problems with your 
Java applications. 


Here is a sample Debugger window, showing many of its features: 


Breakpoint where 
execution has stopped 


Call stack 
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Debugging server objects and client objects You can debug the following objects: 





Server objects 


Objects in deployed J2EE applications: 

e Servlets (including compiled JavaServer Pages) 
e Enterprise JavaBeans 

e Other Java code in deployed J2EE archives 


Other Java applications executing on a server 








Client objects 





Client Java applications, including J2EE application clients 








Local and remote debugging With the SilverStream Debugger you can troubleshoot 
Java applications running on a local host or remotely in a distributed network. You can 
configure a process to be debugged either on the local machine or on a remote machine, but not 
for both in the same session. 


There are many situations that require remote debugging. For example: 


The Java application runs error-free on some machines but not others in a network, 
requiring you to debug the application while it runs on the problematic remote system. 


The application runs in a network where the server is in a remote location. 


The application must be tested on a remote machine that does not have the resources to 
run the Debugger locally. 


Controlling program execution The Debugger provides methods for exercising your 
code by: 


Setting and managing breakpoints in Java application source code 


Stepping in, out, and over source code 


Running applications to a location in source code marked by the cursor 


Running applications to the next breakpoint 


Suspending and resuming threads 


Monitoring program status To help you isolate problems in source code, the Debugger 
provides viewers for examining variables, the call stack, and thread status at any point in 


program execution. 
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Typical workflow for debugging Although each debugging session poses its own unique 
challenges, you typically follow this workflow when troubleshooting applications: 









Launch the 
Debugger 





Manage 
program 
execution 













Analyze 
application 
behavior 






D 


Does it 
work? 








Modify Java 


No—| Source code 


Yes 


Debugging server and client applications The techniques you use to debug 
applications running on a server as opposed to client applications are different. The next two 
sections describe the techniques: 

e Debugging server applications 


e Debugging client applications 
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Debugging server applications 


If you are debugging objects running on a server (such as J2EE applications), you should start 
the application on your server and then attach the Debugger to that application, rather than 
trying to start the application from the Debugger. You can debug applications running on any 
J2EE application server supported by Workbench. 


Starting the server 


In some cases, you must start your application server in debug mode before you can debug 
server objects. This section provides instructions for starting the SilverStream eXtend 
Application Server and BEA WebLogic for debugging. 


LL) For further details about starting these and other application servers in debug mode, 
consult the documentation for the server. 


Starting the SilverStream server for debugging 


> To start the SilverStream eXtend Application Server for debugging: 


e Start the server with one of the following options: 


e +debug starts the server for local debugging, using the default debug address agsrv. 
You can specify these variations for local debugging: 





Variation Description 





+debug:suspend=y Suspends the JVM at startup. Use the 
Continue command in the Debugger to 
resume execution. This option is helpful for 
debugging initialization code that would 
normally get executed before the Debugger 
is attached. 





+debug:suspend=n Does not suspend the JVM at startup. This 
is the default. 














+debug:address=debug_address_ | Lets you specify the debug address to use. 





e  +debugremote starts the server for remote debugging, using the default debug port 
9901. 
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e  +debug:port=port_num starts the server for remote debugging, using port_num 
instead of the default debug port 9901. Use this option if port 9901 is not available. 


Examples This command line launches the SilverStream server for local debugging: 
ServerInstallDir\bin\SilverServer +debug 
This command line launches the SilverStream server for remote debugging: 


ServerInstallDir\bin\SilverServer +debugremote 


Starting the WebLogic server for debugging 


> To start WebLogic for debugging: 
1. Modify your startWebLogic.cmd file by adding the options in bold to the command line 
for starting the server: 


"S$JAVA_HOMES\bin\java" -hotspot -ms6é4m -mx6é4m -Xdebug -Xnoagent 
-Xrunjdwp:transport=dt socket,server=y,suspend=n -Djava.compiler=NONE 
-classpath ... 


2. Start the server. 
When starting, the server will display the debug address: 
Listening for transport dt_socket at address: address 


You will use this value when launching the Debugger, as described next. 
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Launching the Debugger 


You can launch the Debugger from within Workbench or from the command line. 


> To launch the Debugger from Workbench: 
1. Select Edit>Launch Debugger. 


3% Debugger x] 
C Launch new process 


(oj Attach to running process 


Maii 





Arguments 





(oj Shared Memory Debugging 
Address: Fasrv 
C Remote Socket Debugging 


ii 





2. Select Attach to running process. 


3. If debugging an application on a local server, select Shared Memory Debugging and 
provide the debug address. 


If debugging an application on a remote server, select Remote Socket Debugging and 
specify the machine name and debug port. 


NOTE If debugging an application running on WebLogic, even on a local WebLogic 
server, select Remote Socket Debugging and specify the machine name 
(localhost if local) and the address (port) the server reported when starting. 


4. Open files you want to debug in the Debugger, set breakpoints, then run your application. 


> To launch the Debugger from the command line: 


1. Make current the WorkbenchInstallDir\bin directory. 
2. If debugging an application on a local server, enter: 
SilverDebugger -attach localhost debug address 
If debugging an application on a remote server (or a local WebLogic server), enter: 
SilverDebugger -attach machine _name:debug_port 


3. Open files you want to debug in the Debugger, set breakpoints, then run your application. 


Now you are ready to manage program execution and analyze the behavior of your application. 
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A sample debugging session 


In the following scenario, you’ ll see how to debug ProverbFinal, the J2EE application that is 
built in the Workbench’s Web application tutorial. The scenario shows debugging the 
application on a local SilverStream server. (This application is provided as a Workbench project. 
For details, see Tutorials in the Workbench help.) 
1. Start the local server in debug mode. 
ServerInstallDir\bin\SilverServer +debug 

2. Open the ProverbFinal project in Workbench. 

The project is in WorkbenchInstallDir\docs\tutorial\ProverbFinal. It is a completed 

application. 
3. Deploy the application to the server. 


In this scenario, the application was deployed to ProverbsCloud, the Cloudscape database 
provided with the tutorial. 
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4. Open the file to be debugged. 


If you have a file open when you launch the Debugger from Workbench, that file opens in 
the Debugger automatically. You can also open other files in the Debugger to debug them. 


3% SilverStream (ProverbFinal) - Java Editor |. (Of x] 


File Edit View Search Project Documents Help 


T 


=i" ET T E ARLA 






SilverStreanr 





import 
import 
import 
import 








I META-INF 





bublic 
{ 


J ProverbactionServlet,java a] 


a ProverbDataAccess.java 
F| SaveProverbAction.java 
Fi SelectAction. java 

F SelectForm. java 









F) ApplicationResources.properties 
Directory E Project 






Source 


View using: [archive layout [=] layout = C:WVorkbenchProjects\ProverbFinalisrc\com\proverb\TodayAction java x 
28 ProverbFinal. spf import javax.servlet.http.HttpServletRequest; i 
import javax.servlet.http.HttpServletResponse; 
a sof import javax.servlet.http.HttpSession; 
import org. apache. struts. action. Action; 
ES com 


org. apache. 
org. apache. 
org. apache. 
org. apache. 


class TodayAdction 


public ActionForward perform( 


fil ie tee ee] 










struts. action. ActionForm; 

struts. action. ActionForward; 
struts. action. ActionServlet; 
struts. action. ActionMapping; 








extends Action 








ActionMapping mapping, 

ActionForm form, 

javax. servlet. http.HttpServletRequest request, 

javax.servlet.http.HttpServletResponse response 
throws I0Exception, ServletException 






















Here, TodayAction.java was opened. This code is executed when someone asks to see 


today’s proverb. 


5. Select Edit>Launch Debugger to start the Debugger. 


Specify the following: 


C Launch new process 


—— 


@ Attach to running process 





Main class 





@ Shared Memory Debugging 


Address: Fgsrv 
© Remote Socket Debugging 


Host name: 


Port 
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Because the SilverStream server was started using the default debug address, agsrv was 


specified as the debug address. 
The Debugger opens and displays the file. 


Set a breakpoint on a line of code by placing the cursor on the line and clicking the Toggle 


Breakpoint icon in the Debugger toolbar: 


@ Debug localhost: agsrv (TodayAction.java) 
File Edit Tools View Window Help 





Biel es 





evil epps g 


ServletContext ctxt = servlet. get$eryletContexti); 
if (ctxt != null) servlet.log("Got servlet context", 





H 





®| DataSource ds = (DataSource) ctxt. getattribute (Const 
if {ds == null) servlet.log{"DataSource is null", 2) 
if (ds != null) 
E 
servlet. logi" Getting proverb", 3); 
ProverbDataàccess pda = new ProverbDatadccess(ds); 
/ getTod Proverb() should return a Collection o 
if ipda '= null) i 
4| | > 





| 


SilverStream 


a 












"a 














=| ThreadGroup: system 
Reference Handler (2) 
Finalizer (3) 
Signal Dispatcher (4) 
RMI TCP Accept-1 (5) 
RMI Reaper (6) 
GC Daemon (7) 
RMI TCP Accept-2 (8) 
=! ThreadGroup: main 
antiGC (a) 
rawStoreDaemon (b) 


















unknow 
unknow 
unknow 
unknow 
unknow 
unknow 
unknow 


unknow 


unknow s 
» 
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8. Run the application. To do that, open a browser and specify this URL: 
http://localhost/ProverbsCloud/ProverbFinal/index.jsp 





| 4 Words of Wisdom - Microsoft Internet Explorer 


z4 
Forward! 
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9. Click Today’s Proverb. This action invokes code in TodayAction.java. Execution stops 
(you will see that the browser has not completed processing the page) and the Debugger 
window is updated. 



















@ Debug localhost: agsry (TodayAction.java) | |} x] 
File Edit Tools View Window Help 


e 9) i e EEBS e SilverStream 
a 











ServletContext ctxt = servlet. getServletContext(); => com.proverb.TodayAction perform (Todays, 
if (ctxt != null) servlet.log("Got servlet context", org.apache.struts.action ActionServlet proc 
org apache. struts.action.ActionServlet proc 
© DataSource ds = (DataSource) ctxt. getAttribute (Const 


° K org.apache.struts.action.ActionServlet.doGe 
if (ds == null) servlet.log("DataSource is null", 2) iavax.servlet http HttpServlet.service (Https. 
iavax.servlet.http.HttpServlet service (HttpS 
if (ds != null) 

{ 


servlet. logi" Getting proverb", 3); 


ProverbDatadccess pda = new ProverbDatadccess (ds); 
/} getTodaysProverb() should return a Collection o com.sssw.srv.http httpd perform (httpd jave 


if ipda != null) Ad com.sssw.stv.http.Client kiN 
> 


4| | b 4| | 
El 


| com.sssw.srv resources AgvVarResource. 
com.sssw.srv resources AgvVarResource.: 
com.sssw sry. resources AgvVarURLResou 








+ mapping (com.proverb ProverbActionMapping) | [5> clienti (1a) at break 
form (org.apache.struts.action.ActionForm) null client2 (1b) suspen: 

+ request (com.sssw.srv.busobj. A4goHttpRequestEvent) client3 (1c) suspen 

+ response (com.sssw.srv.busobj. AgoHttpReplyEvent) client4 (1d) suspen 
pybs (java.util.Collection) null client5 (1e) suspen 

+ fwd (java.lang.String) "failure" client6 (1f) suspeni 

+l servlet (com.proverb ProverbActionServlet) client? (20) aro | 

+ ctxt (com.sssw.srv busobj. AgovVarServletContext) clients (21) suspen 
ds (javax sql. DataSource) Not in scope client9 (22) suspen 
pda (com.proverb ProverbDataAccess) Not in scope client10 (23) suspen 








client11 (24) suspen w 
4| | b 
locals_/ this” 


am 


You can see that the execution arrow is at the breakpoint. 


10. At this point, step through the code, looking at variable values, the call stack, and so on, as 
described in the rest of this chapter. 


11. When finished debugging, continue execution by clicking the Continue icon: 


The page completes execution. 
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Debugging J2EE applications 


Using the techniques shown in the preceding sample debugging session, you can debug your 
J2EE applications. You debug EJBs and servlets exactly as shown above: open the source code 
for the EJB or servlet in the Debugger, set one or more breakpoints, then run your application. 


Debugging JSP pages 


To debug a JSP page, which is translated and compiled into a servlet for execution, you need to 
locate the Java source file that the server created from the JSP page, open the source file in the 
Debugger, and set your breakpoints. Different JZEE servers will locate their source files 
differently. Here is information about the SilverStream eXtend Application Server and 
WebLogic: 





Server Description 





SilverStream eXtend | The SilverStream server locates its generated source files in its 
Application Server compile cache. 


To find the Java source files the SilverStream server generated 
from deployed JSP pages, look in this directory: 


ServerInstallDir/compilecache/server/database/temp/ 
sources/application/com/sssw/gen/jsp 


For example, to find the source file corresponding to today.jsp, 
shown above, look in: 


ServerInstallDir/compilecache/localhost/ProverbsClou 
d/temp/sources/ProverbFinal/com/sssw/gen/jsp 


You will see a set of .java files corresponding to the JSP pages that 
the server translated into servlets. Files will be named 
name_jsp_nnnnnnnnnn java. 





WebLogic By default, WebLogic does not save the Java source files generated 
from JSP pages. To instruct WebLogic to keep the generated Java 
source code for your JSP pages, specify the value true for the 
keepgenerated parameter in the jsp-descriptor element in 
weblogic.xml. 














(J For information about other servers, consult their documentation. 


To debug a JSP page, open its corresponding .java file in the Debugger, set a breakpoint, and run 
the JSP page. Execution will stop, and you can examine your JSP page. 
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Here, execution has stopped in the Java source file generated from today.jsp: 



















@ Debug localhost: agsrv (today_jsp_1881564134 java) -iof x] 
File Edit Tools View Window Help 


e 9 ü G E peH ge SitverStremr 


throws javax. servlet. ServletException, java.io. IOExca] 
J) com.sssw.gen jsp. today_jsp_1681564134_ 

/ service method intro boilerplate BEGIN com.sssw sry jsp.AgoHttpJspPage service 

JspFactory factory = JspFactory. getDefaultFactory() com.sssw.srv.resources.AgvWarResource.« 

PageContext pageContext = 
_factory.getPageContext(this, request, response, 
null, true, 3192, true); 

c JspWriter out = pageContext.get0uti); 

ServletConfig config = getServletConfig(); 

Object page = this; 

HttpSession session = pageContext. getSession(); 


ServletContext application = config. getServletContex 
ce method intro boilerplate END ad com.sssw.sry.resources.AqvVarResource.t >| 
» 


‘jo | 2. 
z jal 
+l request (com.sssw.srv .busobj.AgoHttpRequestEvent) clienti (1a) at break 











com.sssw.srv.busobj. AgovVarServietReque 
com.sssw stv .busobj. AgovVarRequestDispé 
org.apache. struts action ActionServlet proc, 
org.apache. struts action. ActionServiet proc 
org.apache. struts action. ActionServiet.doGe 
iavax.servlet.http.HttpServlet service (HttpS 
iavax.serviet.http.HttpServlet. service (HttpS 

















+ response (com.sssw.srv.busobj. AgoHttpReplyEvent) client2 (1b) suspen 
strutsbean_message_58 (org.apache.struts taglib.bean Not in scope client3 (1c) suspen 

+l factory (com.sssw.srv jsp. AgoJspFactory) client4 (1d) suspen 

+ pageContext (com.sssw.srv jsp. AgoJspPageContext) clientS (1e) suspen 
out (javax.servlet jsp. Jspyvriter) Not in scope client6 (1f) suspent 
config (iavax servlet. ServietConfig) Not in scope client? (20) sree | 
page (java.lang.Object) Not in scope client8 (21) suspen 
session (javax.servlet http.HitpSession) Not in scope client9 (22) suspen 
application (javax.servlet.ServletContext) Not in scope client10 (23) suspen 
_begRez_strutsbean_message_58 (int) Not in scope client11 (24) suspeni w 
_endRez_strutsbean_message_58 (int) Not in scope xl 4 | | = 


locals AE 


amm ~ | 





Debugging client applications 


In addition to debugging J2EE applications and other applications running on application 
servers, you can also use the Debugger to debug client Java applications. 


When debugging client applications, you can either invoke the Debugger to start the application 
or attach the Debugger to a running application. 
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Invoking the Debugger to start the application 


You can start an application from within Workbench or from the command line. 


> To start a client application from Workbench: 


1. In Workbench, open the project that defines the application. 
Make sure the project’s classpath is set up correctly. 

2. Open the Java source file you want to debug. 

3. Select Edit>Launch Debugger. 


3% Debugger x] 


@ Launch new process 


Main class: | 
Arguments: | 


C Attach to running process 





4. Select Launch new process. 


5. Specify the class to execute and specify any needed arguments. 
6. Click OK. 


> To start a client application from the command line: 
1. Make current the WorkbenchInstallDir\bin directory. 


2. Enter the following at the command line: 


SilverDebugger [options] class class_arguments 
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These are the SilverDebugger arguments for launching an application: 





Argument Description 





options —sourcepath directory_list 


The list of the directories (separated by semicolons) the Debugger 
searches for source files 


NOTE These directories must be source tree roots 





-sourcefile filename 


The fully qualified name of the Java source file to display in the 
Debugger 
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Display usage information for the SilverDebugger command 





—classpath directory_list 


The list of the directories (separated by semicolons) the Debugger 
searches for Java classes used in the application 





—Dname=value 


A system property setting for the application environment 





—Xoption 


A JVM option for the application environment 





class The name of the class to debug 





class_arguments | Arguments to pass to the main() method of class 








NOTE If your source and class files reside on remote network machines, specify paths 
and file names using Universal Naming Convention (UNC) format: 





\\server-name\ shared-resource-pathname 
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For example, to debug the demo Notepad application that comes with the JDK, enter this 
command (where JnstallDir is the installation directory for the demo application, such as 
c:\jdk1.3\demo\jfc\Notepad): 


SilverDebugger -sourcepath InstallDir\src 
-sourcefile InstallDir\src\Notepad.java 


-classpath InstallDir\Notepad.jar 
Notepad 


The Debugger opens on your desktop displaying the Java source file specified. 
3. Set one or more breakpoints in your code or in exceptions. 


4. Select Tools>Continue from the menu or click the Continue icon in the toolbar of the 
Debugger window: 


The application opens on your desktop and execution stops at the first breakpoint 
encountered. 


Now you are ready to manage program execution and analyze the behavior of your application. 


Attaching to a running application 


You can also start the application, then attach the Debugger to it. To do this, you must start the 
application specifically for debugging. 


> To attach the Debugger to a running Java application: 


1. Launch the Java application either on the local host or on a remote machine: 
To launch the application on the local host: 
e Type this command on the command line: 


java -Xdebug -Xnoagent 
-Xrunjdwp:transport=dt_shmem, server=y, suspend=n 
-classpath classpath classname 


The JVM returns a debug address. For example: 


Ma Command Prompt - java -Xdebug -Xnoagent -Xrunjdwp:transport=dt_shmem,server=y,suspend=n -clas... Mi=] EG 


C:\jdki .3.1_@1\demo\ jfc\Notepad> java ~kdebug —Knoagent -Yinin jdeps¢raneporé=dt_shill 


mem,server=y,suspend=n -classpath . -jar Notepad. jar 
Listening for transport dt_shmem at address: javadebug 
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In this example, the JVM returns javadebug as the debug address. The option 
transport=dt_shmem specifies shared-memory transport, which is required for local 


debugging. 
e Note the debug address; you must pass it to the Debugger in Step 2. 
To launch the application on a remote network machine: 


e Type this command in a command line: 


java -Xdebug -Xnoagent 
-Xrunjdwp:transport=dt_socket,server=y, suspend=n 
-classpath classpath classname 


The JVM returns a debug port number. For example: 


Mè Command Prompt - java -Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket.server=y,suspend=n -clas... Mi=] EG 


C:\jdki.3.1_@1\demo\jfc\Notepad>java —Kdebug —Knoagent “ice sahiys tcawepuct-ac-nolll 


cket,.server=y,suspend=n -classpath . -jar Notepad.jar 
Listening for transport dt_socket at address: 3340 





In this example, the JVM returns 3340 as the debug port. The option 
transport=dt_socket specifies socket-based transport, which is required for remote 


debugging. 
e Note the debug port number; you must pass it to the Debugger in Step 2. 
2. Invoke the Debugger either from within Workbench or from the command line. 
To invoke the Debugger from within Workbench: 
1. Select Edit>Launch Debugger. 
2. Select Attach to running process. 
3. If debugging locally, select Shared Memory Debugging and specify the debug 


address returned by the JVM. If debugging remotely, select Remote Socket 
Debugging and specify the debug port returned by the JVM. 


3 Debugger x| 


C Launch new process 
Main class: [otepa Cd 


(oj Attach to running process 


ce Shared Memory Debugging 


Address: favadebug 


C Remote Socket Debugging 
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3. 


To invoke the Debugger from the command line: 


e Use the appropriate SilverDebugger command: 

















For Type this command 
Local SilverDebugger -attach localhost debug_address 
debugging | NOTE debug_address is the address returned by the JVM when you 
launched your Java application for local debugging. 
For example: 
SilverDebugger -attach localhost javadebug 
Remote SilverDebugger -attach machine_name:debug_port 
debugging | NOTE debug_port is the port number returned by the JVM when 
you launched your application for remote debugging. 
For example: 
SilverDebugger -attach mymachine: 3340 





The Debugger opens on your desktop. 


Open a source file for debugging using File>Open. 


Now you are ready to manage program execution and analyze the behavior of your application. 


Debugging against SilverJRunner or SilverJ2EEClient This is just like debugging 
against a SilverStream server. You launch SilverJRunner or SilverJ2EEClient with an 
appropriate debug startup option (described in “Starting the server” on page 6), then attach the 
Debugger to the resulting debug address (default is agjrn) or debug port (default is 9901). 


Managing program execution 


Once you have started the Debugger, there are several ways to manage program execution to 
allow you to isolate and diagnose problems in the source code: 


Using breakpoints 


Continuing execution 


Stepping through the code 
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Using breakpoints 


You use breakpoints to specify lines in your code where you want to stop execution and give 
control to the Debugger. When the code stops executing and the Debugger takes control, you 
can execute Debugger commands and view the call stack, thread status, and variable values. 


You can set breakpoints only on individual lines in your code. If a line contains multiple 
statements, you can set a breakpoint only on the first statement in the line. To set breakpoints on 
the subsequent statements, you need to break up the line so that each statement appears on its 
own line. 


NOTE Breakpoints are stored by server name and class name. As a result, like named objects 
on the same server share breakpoints. 


Setting and removing breakpoints in code 


There are several ways to set and remove breakpoints in code, either for local classes or classes 
loaded from external sources. If the Debugger cannot find the source code, it prompts you for a 
path, as described in “When the Debugger cannot locate source code” on page 26. 


This section describes the procedures for setting and removing breakpoints in source code. 


> To set breakpoints in code using Toggle Breakpoint: 


1. Put the cursor at the line in the source code where you want to set a breakpoint. 


2. Either choose Tools>Toggle Breakpoint from the menu or select the Toggle Breakpoint 
icon in the Debugger toolbar: 


The breakpoint indicator © appears in the left margin beside the line you specified. 


> To set breakpoints in code using the Edit menu: 
1. Select Edit>Show Line Numbers from the menu. 
This makes it easier to specify locations for breakpoints. 
2. Choose Edit>Breakpoints from the menu. 
The Manage Breakpoints dialog opens. 
3. Select the Code tab. 
The dialog lists all breakpoints that have been set. 
4. Click Add. 
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5. Do one of the following: 





To insert a breakpoint in | Do this 





Your local Java class 1. In the Specify Breakpoint field, enter the location 
where you want to add a breakpoint, in this form: 


<fully qualified class name>:<line number> 
Example: 
com.myapp. gui.CheckBoxes:99 

2. Click OK. 





pai 


Loaded classes . Click Browse. 


2. Navigate to the method where you want to insert a 
breakpoint and click OK. 


The breakpoint specification appears in the Specify 
Breakpoint field. 














The new breakpoint appears in the Manage Breakpoints dialog. 
6. Click OK. 
7. Click Done to add the breakpoint to the source code. 


> To remove individual breakpoints using Toggle Breakpoints: 


1. Click in a line that has a breakpoint. 
2. Select the Toggle Breakpoint icon in the Debugger toolbar. 


> To remove breakpoints using the Edit menu: 
1. Choose Edit>Breakpoints from the menu. 
The Manage Breakpoints dialog opens. 
2. Select the Code tab and click to select the breakpoints you want to remove. 
3. Click Delete. 
The breakpoints disappear from the list in the Manage Breakpoints dialog. 
4. Click Done. 


The breakpoints disappear from the source code. 
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> To remove all breakpoints: 


e Select Tools>Clear All Breakpoints from the menu or click the Clear All Breakpoints 
icon in the Debugger toolbar: 


2 


Setting and removing breakpoints in exceptions 


In addition to setting breakpoints in the main body of source code in your Java applications, you 
can set breakpoints in standard Java exceptions or in exceptions that you write to handle specific 
behaviors. 


This capability can help you pinpoint the source of exceptions that are thrown unexpectedly 
when you run your application. When you set a breakpoint in an exception and then run your 
application, the Debugger will stop where the exception gets thrown and display the offending 
source code if it is available for the class you are debugging. If the Debugger cannot find the 
source code, it prompts you for a path, as described in “When the Debugger cannot locate source 
code” on page 26. 


> To set breakpoints in exceptions: 


1. Choose Edit>Breakpoints from the menu. 
The Manage Breakpoints dialog opens. 

2. Select the Exception tab and click Add. 
The Add Exception Breakpoint dialog opens. 


3. Type the fully qualified name of the exception class on which you want to break, or click 
Browse to select an exception from the list of loaded exceptions. 


4. Click OK to return to the Manage Breakpoints dialog. 
The new breakpoint is listed. 
5. Click Done. 


NOTE Exception breakpoints do not appear in the source code. 


> To remove breakpoints from exceptions: 


1. Choose Edit>Breakpoints from the menu. 
The Manage Breakpoints dialog opens. 
2. Select the Exception tab and click the breakpoints you want to remove. 
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3. Click Delete. 
The breakpoints are removed from the list. 
4. Click Done. 


Enabling and disabling breakpoints 


The Debugger allows you to enable and disable breakpoints in code and exceptions. Disabled 
breakpoints appear with a grayed icon: 


> To enable breakpoints: 
1. Select Edit>Breakpoints from the menu. 
The Manage Breakpoints dialog opens. 
2. Select the Code or Exception tab to locate the breakpoints you want to enable. 
3. Click the breakpoints you want to activate and click Enable. 
4. Click Done. 


The breakpoints you selected will be enabled when you continue program execution. 


> To disable breakpoints: 
1. Select Edit>Breakpoints from the menu. 
The Manage Breakpoints dialog opens. 
2. Select the Code or Exception tab to locate the breakpoints you want to disable. 
3. Click the breakpoints you want to activate and click Disable. 


To select multiple breakpoints: hold down the Ctrl or Shift key when you click each 
choice. 


4. Click Done. 


The breakpoints you selected will be disabled when you continue program execution. 


Continuing execution 


When the program stops at a breakpoint you can continue execution using the Continue or Run 
to Cursor commands in the Debugger: 


e Use the Continue command to resume running the program to the next breakpoint it 
encounters. 





24 Managing program execution 





eXtend Workbench Tools Guide 





e Use the Run to Cursor command to continue running the program to a specified location 
in the code, marked by the cursor. 


When the program reaches a breakpoint, the Debugger window is activated and an arrow (called 
the execution pointer) appears in the margin to the left of the code indicating which line is 
about to be executed. 


Along with the execution pointer, the Debugger displays a list of local and instance variables 
and enables the commands for stepping through your code. 


> To continue execution: 


e Select Tools> Continue from the menu or click the Continue icon in the toolbar of the 
Debugger window: 


The Debugger executes your source code until it reaches the next breakpoint. 


> To run to a specified location in the source code: 


1. Click in the line of code where you want execution to stop. 
The cursor must be located on a line that contains executable statements. 


2. Select Tools>Run to Cursor from the menu or click the Run to Cursor icon in the 
toolbar of the Debugger window: 


| 


Run to Cursor executes your code from the current execution location until it reaches the 
place where the cursor is located. If you have breakpoints set and a line containing a 
breakpoint is executed before the line that has the cursor, Run to Cursor stops execution at 
that breakpoint line. 


NOTE Ifyou put the cursor on a line that doesn’t get executed—for example, if your 
cursor is on the first line of code inside an if statement when the if condition 
evaluates to false—the effect of executing Run to Cursor will be the same as if 
you select the Continue command. 
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Stepping through the code 


There are three Step commands included in the SilverStream Debugger: 





Command Executes Details 





Step Over The current line If the current line contains a method call, that method 
is executed. The Debugger stops at the line 
immediately following the line that was executed. 





Step In The current line If the current line contains a method call, the 
Debugger stops at the first line in the called method. 
Otherwise, the Debugger stops at the line immediately 
following the line that was executed. 


If the Debugger cannot find the source code for the 
method it has entered, it prompts you for a path, as 
described in “When the Debugger cannot locate 
source code”, next. 





Step Out The remainder of | The Debugger stops at the statement immediately 
the current following the statement that called the current 
method method. 

















When the Debugger cannot locate source code 


When the Debugger cannot locate source code for a particular operation, it prompts you to 
provide the path to the source file. Either provide the path or dismiss the prompt and follow 
directions to either continue execution or step out of the current method. 


Analyzing the behavior of the application 
You can examine the current execution state at three points: 


e When the Debugger stops at a breakpoint 
e Following a Step command 
e When you suspend and resume threads 


At each of these points you can view the following information: 


e Call stack 
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e Thread status 


e Local and instance variables 


Viewing the call stack 


The Debugger provides a viewer that lets you examine the call stack during program execution. 
The call stack viewer shows the name of each method in the stack, along with its source file and 
line number. 


When you double-click a method in the call stack viewer, the source file opens in the Debugger, 
highlighting the line where the method is called. If the Debugger cannot find the source file, it 
prompts you for a path, as described in “When the Debugger cannot locate source code” on 
page 26. 


The call stack viewer updates the call stack when: 
e The Debugger stops at a breakpoint 

e You execute a Step command 

e You continue execution to the next breakpoint 


e You continue execution to a specific location in the code, marked by the cursor 


e You select a different thread 


> To open the call stack viewer: 


e In the Debugger, choose View>Call Stack from the menu. 


A pane for viewing the call stack appears in the Debugger window. 


Viewing threads 


The Debugger provides a viewer that lets you examine the status of threads during program 
execution. The thread viewer displays threads organized by groups, showing the name of each 
thread, along with its identifier and state. 


You can suspend and resume threads to isolate problems that occur in thread synchronization, 
such as deadlocks and infinite loops. 


The thread viewer updates thread status when: 


e The Debugger stops at a breakpoint 
e You execute a Step command 


e You continue execution to the next breakpoint 
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e You continue execution to a specific location in your code, marked by your cursor 


e You suspend and resume threads 


> To open the thread viewer: 


e In the Debugger, choose View>Threads from the menu. 


A pane for viewing threads appears in the Debugger window. 


Interpreting thread states 


Threads can exhibit a variety of states during program execution: 


























Thread state Description 

At breakpoint Thread was running when execution stopped at the breakpoint 

Running Thread is running 

Sleeping Thread is sleeping for a specified period of time 

Suspended Thread is suspended 

Waiting Thread is waiting for notification to resume running 

Waiting on monitor Thread is waiting for a monitor to be released by another thread 

NOTE In a deadlock situation, you will see two or more threads in 

this state. However, threads that appear in this state do not 
necessarily indicate a deadlock. 











Suspending and resuming threads 


If you encounter an infinite loop or deadlock in a thread, you can isolate the problem by 
suspending the thread and viewing its call stack. You cannot view the call stack of a thread 
unless it is suspended. 


> To suspend a thread and view its call stack: 


1. Open the thread and call stack viewers. 
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2. Do one of the following: 





To suspend Do this 





All threads 1. Stop execution of the code at a breakpoint. 


2. Click the suspended thread. 





An individual thread | Double-click a running or waiting thread in the thread viewer 














The call stack for the selected thread appears in the call stack viewer. 
3. Double-click methods in the call stack to view their code in the Debugger. 


If you double-click a waiting thread, the method that put the thread in a wait state appears 
in the call stack viewer. 


If the Debugger cannot locate the source code for a method you selected, it prompts you to 
supply a path, as described in “When the Debugger cannot locate source code” on 
page 26. 


> To resume a thread: 


e Do one of the following: 











To resume Do this 
All threads suspended ata | Resume execution of your application by: 
breakpoint ee: 
e Stepping in, out, and over source code 
e Running the application to a particular location in the 
source code, marked by the cursor 
e Running the application to the next breakpoint 
e Continuing execution 
An individual thread Double-click the suspended thread in the thread viewer 














Viewing variables 


The Debugger provides a viewer that lets you examine local and instance variables when 
program execution stops at a breakpoint. The variable viewer displays the variable name, type, 
and value. 
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The variable viewer updates variable values when: 


e The Debugger stops at a breakpoint 


e You execute a Step command 


e You continue execution to the next breakpoint 


e You continue execution to a specific location in your code, marked by your cursor 


> To open the variable viewer: 


1. In the Debugger, choose View> Variables from the menu. 


A pane for viewing variables appears in the Debugger window. 


2. Click locals to view local variables and click this to view instance variables for the current 


object. 


Debugger keyboard shortcuts 


Use these keyboard shortcuts. 



































Keystroke Description 
Ctrl+C Copy to Clipboard 
Ctrl+G Go to line number 
Ctrl+F Find/Replace 

F5 Continue 

F10 Step over 

F11 Step in 

Shift+F11 Step out 

Ctrl+F10 Run to cursor 
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